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Preface 



tNt extends Xll/NeWS® in two areas, offering: 

■ classes of objects that implement the OPEN LOOK™ Graphical User Inter- 
face, and 

■ the Wire Service, an enhanced means of communication between the 
server and a client program. 

To see what this means to you, let's put it in perspective, beginning with the 
generic model of a window system shown below. 



Figure 1: Generic Window Architecture 



Application 
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Starting from the hardware, each layer of software manages resources and 
extends the capabilities of the system. 

The operating system manages hardware resources, and provides services to 
access them. The type of management and service can vary widely. Simple 
operating systems manage the hardware resources, sophisticated operating sys- 
tems extend those resources. For example, even primitive operating systems 
include a file system of some sort. The file system takes raw ir\ass storage and 
turns it into files and directories of files. More sophisticated operating systems 
(certainly anything that supports Xll/NeWS, such as UNIX® offer multitasking. 



Preface 



1 










Preface 



which does the same thing for the raw processor/memoiy resource, turning it 
into multiple jobs apparently executing at the same tinne. 

The next layer up in the generic model, the window system, applies this same 
philosophy to the display resource. The window system takes a raw high reso- 
lution display and turns it into multiple virtual displays called windows. 

The window system toolkit provides another level of service in allowing you to 
manupulate the appearance and function ('look and feel") of the windows. The 
toolkit provides varying degrees of assistance to the application in defining the 
interface the application's user will see. In some cases the toolkit offers assorted 
user interface components for the application builders to use as they see fit. In 
other cases, the toolkit implements (and enforces) a standard user interface to be 
used by all applications. 

The situation with Xll/NeWS is shown in Figure xnewsarch below. What is 
unique to Xll/NeWS is that there are two toolkits, one for Xll™ applications 
and one for NeWS applications. Both toolkits implement the emerging OPEN 
LOOK graphical user interface standard. 
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Figure 2: X11/NeWS Architecture 
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Sun 3,4, SPARC™, 386i 



This manual does not address the X Window™ side of Xll/NeWS, but it is 
important to remember that it is there because you will occasionally run across 
things that owe their existence to the XI 1 side. 



What’s in the Chapters 

The chapters are: 

Chapter 1, "Introduction” is a brief introduction and includes information on 
running tNt demos. 

Chapter 2 , "The Wire Service" explains the tNfs enhancement to NeWS' support 
for client-server communications. 

Chapters, "Canvases" provides details on ClassCanvas which provides the basic 
underpinning for windows, menus, and controls. 
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Chapter 4, "Managing Groups of Canvases" explains about bags. When you 
need to bring a group of canvases together to accomplish some task you'll use a 
bag to manage them. This chapter also contains information about managing 
the input focus. 

Chapter 5, "Menus and Other Selection Lists" explains how tNt enables you to 
build menus quickly and associate them with canvases. 

Chapter 6, "Controls" explains about the different kinds of controls tNt pro- 
vides. Some kinds of controls are scroll bars, sliders, dials, and buttons. 

Chapter 7, "Graphics" contains information on the tNt facility for providing 
images for buttons, menus, controls and labels without the overhead of using 
canvases. 

Chapter 8, "The NeWS Development Environment Input Model" is a 
comprehensive, in-depth look at the facilities tNt has added to the NeWS sys- 
tem for handling user input. 

Chapter 9, "Selections" explains how tNt handles user selection of objects like 
text and windows. 

Chapter 10, "Miscellaneous Topics" has information on ClassTarget, tNt's class 
that helps manages references to other objects and helps prevent dangling refer- 
ences. This chapter also contains information that helps to define what an tNt 
application is. 

Chapter 11, "Interface Reference" contains the details of the function calls of the 
Wire Service and the method interface for selected tNt classes. 

For further information on the OPEN LOOK Graphical User Interface, please 
consult: 

■ OPENLOOK Functional Specification 1.0 Sun Microsystems Inc., part 
number 800-3355-05. 

■ OPEN LOOK UI Style Guide, Sun Microsystems Inc., part number 800- 
3356-06. 

For information on the XI 1 /NeWS server, see: 

■ NeWS Programmer's Guide, Sun Microsystems Inc., part number 800-2379- 
04. 
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For information on the PostScript® Language, see: 

■ PostScript Language Reference Manual, Adobe Systems Inc., Addison Wes- 
ley, 1985, ISBN 0-201-10174-2. 
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Introduction 



The News Development Environment provides a powerful and flexible exten- 
sion to the NeWS window system. It is object-oriented in design and imple- 
ments much of the look and feel described in the OPEN LOOK UI specification. 

The toolkit is composed of two pieces: a set of PostScript classes which imple- 
ment parts of the OpenLook specification, and completely replaces the Lite 
toolkit; and a C library, called the Wire Service, which sigruficantly enhances 
CPS as the client/server communications package. 

The two parts of the toolkit are quite independent. You can use only the 
PostScript components in a server-resident program, or even communicate with 
a client process via unadorned CPS. Similarly, the Wire Service does not rely on 
the PostScript classes at all, and could theoretically be used with any other 
server-side toolkit. 



Philosophy 

The philosophy behind the PostScript-based portion of the NeWS Development 
Environment is to provide a useful set of OPENLOOK components, under- 
pinned by a powerful and flexible set of intrinsic classes that are not specific to 
any particular user interface. 

The Wire Service is intended to provide the lowest common denominator in 
client-server communications needs. It handles registration of client-side call- 
backs, a notification mechanism by which to call them, and a synchronization 
system for server /client communication. It is almost transparent in its simpli- 
city. 



Learning the System 

As with any powerful system, the NeWS Development Environment takes some 
effort to learn. To help you learn to get all the power out of the toolkit, 
demonstration code has been built directly into the the class hierarchy. This 
comes in the form of /demo methods in many of the classes. However, in order 
to decrease the size of the code that the toolldt loads into the server, the demo 
methods are not available by default. To enable them you must put the follow- 
ing line in the .user.ps file in your home directory. 
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systemdlct /IncludeDetnos? true put 

Two files, bag-example.ps and selections-example.ps have been included on the 
tape that includes this documentation. Once you've started the server you can 
execute these examples via psh(l). Complete listing of the code for these exam- 
ple can be found in the following chapters: 

bag-example.ps Chapter 4. Managing Groups of Canvases 

selections-example.ps Chapter 8. Selections 



Conventions 

Several conventions are used in this manual: 

■ Toolkit methods are in bold. 

■ PostScript operators are in helvetica-bold. 

■ Code examples are in 1 0-point helvetica. 

■ At the beginning of major sections the relevant portion of the toolkit's 
class tree is reproduced to provide a connection between the subject being 
discussed and its location in the class hierarchy. 



1-2 



tNt Technical Reference Manual 





2. WIRE SERVICE 



2. WIRE SERVICE 




The Wire Service 



The Wire Service 

Purpose of the Wire Service 
An overview of the components 

■ The Notifier 

■ Connection Management 

■ Resource Allocation 

■ Server-client synchronization 

Notification 

Connection Management 
Resource Allocation 

■ Tag Allocation 

■ Token Allocation 
Server-Client synchronization 
Building a typical application 



2-1 

2-1 

2-1 

2-1 

2-1 

2-2 

2-2 

2-2 

2-5 

2-8 

2-8 

2-9 

2-11 

2-12 



Table of Contents 



I 





The Wire Service 



Purpose of the Wire Service 

The News Wire Service is a server-client communications package that provides 
support and management of server connections, a client notifier, and shared 
resources. The Wire Service has four primary components: a notifier, a connec- 
tion manager, a tag/token allocator, and a server-client synchronization 
mechanism. 

Connection management enables a client to initiate multiple connections to one 
or more servers. Allocation of handles allows the C language to reference 
PostScript objects in the server (Tokens) and the PostScript language to reference 
C objects in the client (Tags). Event notification associates client procedures with 
specific events. When the event is received, the notifier will execute the 
appropriate procedure. Synchronization permits a server process to pause and 
wait for notification from a client process. 



An overview of the components 

The Notifier 

The Notifier provides a lightweight mechanism for allowing clients to register 
callback functions associated wiA as)mchronous messages from the server(s). 
Using the tag allocator, a client reserves a range of tags and associates a C pro- 
cedure with each tag. When a tag is read from one of the server connections, the 
Notifier invokes the appropriate procedure. The notifier supports both applica- 
tions that wish to "own" control of the main loop construct (e.g., Macintosh 
style applications) and those that wish to be solely callback driven (e.g.. Sun- 
view style). 

Connection Management 

Connection management is the second major component of the Wire Service. 

An application can open a single connection to a NeWS server or multiple con- 
nections to a single server or multiple servers. A connection is abstracted to the 
notion of a Wire and facilities are provided for various forms of manipulation 
(opening, closing, temporarily disabling, etc.). Events from the server come 
back on the wire and are read using normal CPS operations (see the NeWS 
Programmer’s Guide). 
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Resource Allocation 

There are two resource allocators in the Wire Service: a tag allocator and a 
token allocator. While they have parallel architectures, they have complemen- 
tary purposes. Tags are used to keep a handles toC procedures that can be used 
in the server, and tokens are handles to server objects for client manipulation. 

Tags are allocated individually or in ranges on a per-client basis. Thus a single 
tag/callback pair that is registered with the Notifier can be used from multiple 
wires (and hence multiple servers). To provide compatibility with tag usage in 
applicatioirs written with statically defined tags, a range of tags can be reserved 
and removed from the allocator. 

Tokens are also allocated individually or in ranges but, unlike tags, tokens are 
allocated on a per-connection basis. Since there is no counterpart to the Notifier 
in News, the application is responsible for the registration of the token in the 
server as well as keeping track of the wire/token association. Tokens, as pro- 
vided by the Wire Service, are implemented by using the usertokens provided 
by CPS. To provide compatibility with applications written using the userto- 
kens, a range of tokens can be reserved and removed from the allocator. 

Server-Client synchronization 

The final component of the Wire Service is the server-client synchroiuzation 
mechanism. CPS provides a mechaiusm for a client process to block pending 
notification from a server process. The Wire Service provides a complementary 
mechanism which will allow a server process to block pending notification from 
a client process. This provides s)mrunetrical facilities for synchronous conununi- 
cations. 



Notification 

The notifier in the wire service reads a single tag from one or more server con- 
nections. Depending on its value, the tag is then dispatched to a user defined 
procedure. Before the message is dispatched, the notifier will set the PostScript 
and PostScriptInput pointers to the appropriate connection. 

wire_RegisterTag associates a pointer to a function and a pointer to client data 
with a specific tag. When the tag reaches the head of the input queue, the 
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notifier calls the function. The client function associated with a tag can be 
retrieved using wire JTagFunct ion. The client data is retrieved using 
wireJTagData. 

Two modes of notification are offered. For event-driven applications, 
wire_EnterNotifer will allow the notifier to control the dispatch of tags until 
wire__ExitNotifier is called. In this model, the application can eliminate con- 
trol loops related to tag processing. On the other hand, applications which are 
not event-driven might need to maintain finer control of message processing. 
Using wire__Notify, these programs can implement a control loop and still use 
the notifier to dispatch messages. 

The wireJWouldNotify function reports whether there are pending tags on the 
input queue of a particular wire or all wires. wire_SkipEvent consumes the 
initial tokens on the wire until the next tag is detected. When no input is pend- 
ing, this function will not block. 

Example 







file demo.c: 


1 include 


<wire.h> 


♦include "den^ojcps.h” 
♦define DATA "data" 
int 


MouaeMoveTag; 


int 


MouaeDownTag; 


int 


MouaeElxitTag; 


int 


^MouaeTagatl “ {^MouaeMoveTag^^MouaeDownTag, &MouaeExitTag^ 0 


void 


MouaeMove () ; 


void 


MouaeDown () ; 


void 


MbuaeBxit <) ; 


main(argc# argv) 




int argc; 




char *argvn; 

( 

n#ire_Wire 


thiaWire; 


if 


((thisWire * wireJ5pen (NULL) ) — wireJENVALID_WIRE) { 


wire^Perror (argv I 0] ) ; 


exitT-1) ; 


wire_AllocateUair>edTags (MDUseTags) ; 







(continued on next page ) 
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wii?e_R©gl«terTag(Mc>u9eMi5veTag^ Mou^eHove/ l«UJ*L>/ 

wiceJ^ldt^rTag (McmseDownT MoiuioDown> JDASA); 

wlre^RegisterTag (MouseExitTag, MouaeExit# NULLy; 

cps^RegiaterTags (M6uaeM?v©Tag^ MouseDownTag, MouseBxitT^) ; 

cps^MouseMoveTag <> ; 

wire_Notify< (struct timaval *)0); 

cps^MousaMovaTag () ; 

cps^JfouseDowntag <> ; 

cps^MouseExitTag <y ; 

wlreJBater«totifier() ; 

wire Close (thlsWire); 



void 

KousaMovo (tag, data) 
int 

caddr__t 



printf ("MouseMove\n**y ; 
wirejSkip^vent () ; 



MbuseDown (tag« data) 

int t 

caddr_t data; 

printf (’*Mou3aDo«m\n'*) ; 
printf ("Data « %s\n*^r data); 
wirejSkipBventO; 



void 

MousciExit (tag, data) 
int 

caddr_t data 

lilllllllllli 

pxintf ( "MouseExit\n"y ; 

wire BxitNotlilerO; 



file demo_cps.cp8: 



cps_RegiaterTags (MouseMoveTag, MouseDownTag, HpuseBxitTag) 



(continued on next page ) 
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lull 

/HoveTag HouseHtTveTag 6e^ 

/DownTag MouaaDounTag da£ 

/Exi^Tag MouaeBxitTag def 

cdef q)3 J^MisetfoVeTag 0 

MpvaTag tagprint; 
cdaf cpa^HoudeDownTag 0 

Do%inTag tagprixit 

cdef qpa^HouaeExitTag 0 

BxitTag tagprint 

J 



Connection Management 

The client connection to one or more servers is established using the wire ser- 
vice function wirejOpen. One parameter is passed to wire_Open to indicate 
the server. This parameter can take three forms: 

■ A null value implying the default server named in either the NEWSSERVER 
or DISPLAY environmental variable. 

■ A parameter in the format "hostname", meaning the default server on the 
specified host. 

■ A parameter in the format of either the NEWSSERVER string or DISPLAY 
string (see the Xll/NeWS Server Guide) to direct the connection to the 
appropriate host. 

When the connection to the server is successful, a wire_Connection structure 
is allocated in the wire connection table. This is returned as a wire_Wire and 
is used as a handle to refer to the connection in subsequent calls. 

During the open process, the connection is enabled through a call to the 
wire_Enable. One parameter, a wire_Wire, is passed to wire_Enable to 
indicate the appropriate connection to activate. In addition, another function, 
wire_Disable is available to disable a connection should the application need 
to ignore input from the server for a limited time. To disable a wire, the call 
wire Disable (theWlre) is made. 
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The CPS functions and the server communicate using the PSFILE pointers, 
PostScript and PostScriptInput. Therefore, the wire service introduces the con- 
cept of the "Current Wire." Whenever a wire_Wire becomes the current wire, 
its file pointers are moved into the global variables, PostScript and PostScriptIn- 
put. Thus all CPS conamunication takes place on the Current Wire To make a 
wire the "Current Wire", a call to wire_Set Cur rent (theWire) is made and 
becomes the current wire. The current wire is returned by a call to 
wire_Current () . 

Each connection has three function pointers for handling abnormal conditions: 
death, disease, and unknowntag. 

When the connection is terminated abnormally (not via a call to 
wire_Close () ), the death function is called. 

When the first token in the input queue is not a tag, the notifier calls the disease 
function. This function is responsible for consuming the offending tokens. 

When the first token in the input queue is not a registered tag, the notifier calls 
the unknowntag function. 

wire_Open provides the new wire_Wire with default functions for these 
problems. The wire_Problems function can be used to register private 
handlers. This function requires four parameters: a wire_Wire, a death func- 
tion pointer, a disease function pointer, and a unknowntag function pointer. A 
null function pointer value will leave the current function unchanged. 

The wire_Close function terminates a connection to the server. The 
wire_ALLWIRES constant can be passed to wire_Enable, wire_Disable, 
wire_WouldNotify, and wire^Close to effect all connections. For example, 
the call, wire_Close (wire_ALLWIRES) , would terminate all connections. 

An application might need to maintain state information. The wire_SetData 
function can associate a client data pointer with a connection. The information is 
retrieved using wire_Data. 

The application can deternune the current wire using the wire_Current func- 
tion. The wire_Valid function will indicate whether a particular wire is opera- 
tional. 
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Example 

/ . — — — — 

fincluda <Mit& .h> 
nrqv} 

int axgc; 
qhay ^argvtl; 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii 

dhaJit reliant; 

ohar “^atata • **3tata £nfprinatipn>”; 

irfirajlita thldWira/ 

ifl£a]Wl£a tbattfixa; 

((thiaWiw - ( 

wi wijNarror (argv l?J ) ; 

iiiiiiiiiiiiiliiiiiiliiii^iiiiiiiiiiili 

thatMixa •• vixBjCorxeititO f 
if (thiaWiza thatWiza^ 

printfi^itha tk6M itfixa 1$ tha cixtxaat i^ixaVk**); 
if <wiza^Valid(tihiaWita) j| 

printf<’*Tha ww i#i»a i» opafraticini(iVa**> ; 
if (vrixajSatDataCthlaMlta^ atata)i) 

prlntf(**Tha naw wiza haa qliant data ; %aSa”» atata); 

if ((Qlient >« 4^i£aJ)ata(thi$ttizan && (atzt9iip<aliaiat« $tate) 0)) 
printf(”Tha aiiant data haa k>aan zatclavad\n”K* 

Wika^Disable (thiaWlta) ) 
if (UwixaJBaabied(thiaWi¥a>^> i 

printf<^3!ha timt nira ii^aa dlaabilad\a^>; 
wira^Ehabia <t;hi»wlraj> ; 

aizaj^iosa (thlawiza) ; 
if (T(wizaJ/aiid(thlaWlra))) 

pzlntf <**!i:ba ti6iu Wiza has bean cloaed and la hO longer operatiOnal\n^> ; 
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Resource Allocation 

Tag Allocation 

Using the CPS libraries, the programmer is responsible for the allocation of tags. 
Without careful supervision, applications may duplicate tag values, leading to 
confusion and madness. The wire service provides routines to allocate or reserve 
a range of tags. Tags are no longer constant values, but are generated in a 
dynamic manner. In addition, tags can be assigned to a list of client variables. 

wire_AllocateTags reserves a range of client tags. This function is passed an 
integer (N), which indicates the number of tags required. It returns an integer 
(M), ensuring that the tag values, (M) through (M+N-1), have not been allocated 
in the past. 

wire_ReserveTags allows the wire service to coexist with both CPS and 
private tag allocation schemes. This function is passed an integer (N), which 
represents the highest tag value to be reserved. wire_ReserveTags should be 
executed prior to wire_Open and wire_AllocateTags. 

wire_AllocateNamedTags assigns tag values to client variables. This func- 
tion is passed a null terminated array of pointers to integers. It reserves and 
assigns a tag value to each of the pointers. 
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Example 



f include 
fdefine 
int 
int 
int 

tnain(ez 9 c 
int argc; 
Char *argvtl; 
( 



<wize.h> 



CXJHSTWT_TAGS 100 
HoudeMdveTag; 

MouseDQVfnTeg; 

*Mou3«iTag5n ** ( ^IcnseHbveTag^ 



(HcusePowiTag/ Q ); 



a»gv> 



vireJWij» thiswire; 

wireJtesexveTaga (CONSiauwjC^) ; 

if (TthisWire » wirejOpen'oTOLLJ ) — wlre_INVALIDJJIREy { 
wire^Perror(axgv [0] ) ; 
exit (-1) ; 

iiiliiiiliiliiiiliilliiiiiil 

wire^AIlocatellainddTagd (HduaeTags) ; 
printf C*MouseMc>V0Tag •* %d\n**« NouseNoveTag) ; 
printf ("MouseDownTag - %d\n"/ HcuseDoim^Tag) ; 
wire Close (thiaWire) ; 



Token Allocation 

The Wire Service references server objects through user defined tokens (usertoken 
as defined in CPS). wire_AllocateTokens, wire_ReserveTokens, and 
wire__AllocateNamedTokens are similar to the tag allocation functions, with 
some exceptions. For instance, tokens are allocated on a per connection basis, 
either tokens must be used with the connection they were defined on or care 
must be taken to align tokens across connections via the use of 
wire_ReserveTokens. In addition, the application is responsible for register- 
ing the usertokens in the server. 



The Wire Service 
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The Wire Service 



Example 



file iem^i 

lincltidd 

#lnqi\ 2 d 9 

iht 

int 

int 

minivpgc, «gv) 
int at^c; 

Qhar *argvl]; 



<wi*».h\> 



X 



l^irdo%rt? 6 k 6 tt; 

MyButtonTok^n; 

*M/Tdkana {3 * { (M^lndoi^Tolcan^ «HyButtonXofcdn« 0 



> wira^INVALIDJHIRE) t 



\ 



wlxd^Mlxd thiaWitd; 

if ((thlaWire «• wiinaJDpeii(Nin<L))i 

wirej?artx>r (at<gv {03 ) ^ 
exit (*•!> ; 

lllllll*^^^^ 

wlxejUiocateKainddTokend(thi 3 Hix^^ l^okens>; 

/* If the aame tphena eze to be ueeel en another connection, 
* othezwize/ the foXXoeing Une wonXd he naed. Note that 
Myduttontoken la the laat in the i^okena attay« 

*' wite^ReserveTokena (otherHire, MySuttonToken^; 

pajC*eateWfyWindow (J^tndowToken) s 

wij?ej2Xo«e(thiaWize) ; 



file 4moj:p$,cps^ 

odef paj3reate*^indow<int token) 

« . . /new HyWindovCXaas aend 
token aetfileinputtPken 

cdef pa jMapMindow (token i^indow) 
/map MyWindow aend 



% t^indow inatance on atack 
% Beglater the uaertoken/Window pair 



% l^lndow geta looked »p autcmatioally 
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Server-Client synchronization 

The synchronization mechanism provided by the wire service allows a server 
process to initiate a synchronous call to the client. A call is made to the 
PostScript function wire_Synch with an executable procedure on the stack. 

The procedure is executed and then wire_Synch sends a marker to the client. 
The server process then blocks until the client acknowledges receipt of the 
marker. 

One of the more common uses of this facility will be to paint of canvases that 
need some functionality in C for repainting. The server, upon getting the 
PaintCanvas request, initiates the client code and then blocks before painting the 
rest of the canvas. In the example below, the client will handle the 
REDRAW_TAG before acknowledging receipt of the marker. This would allow 
the client to paint the rest of the canvas, if desired. 

wire_Synch expects to find the user diet on the dictionary stack. If 
wire_Synch is to called from another process, make sure that the necessary 
information is in the current user diet. 



Example 




The Wire Service 
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The Wire Service 



Building a typical application 

A typical application consists of three or more files containing the C routines, 
the code to 1^ loaded into the server, and the cps code. 

main . c: This file would contain the C code for the application. It should 
include the file <wire . h> and ”main_cps . h” and be linked with libwire.a and 
libcps.a. 

maintops . cps: This file should contain the CPS code for conamunicating to the 
server. It should be run through the CPS preprocessor to generate main_cps . h 
which is included in main.c 

main.ps: This contains most of the PostScript code needed by the application. 

It is typically loaded through a CPS call defined in maintops . cps. 

Note: Assuming that the environment variable $OPENWINHOME is set to the 
directory containing a properly installed version of OpenWindows, then the fol- 
lowing consists of a sample compilation: 

$ $OP£MWXNMOHE/bin/cpd malnjCii^d.tips 

$ cc $OPBNWJNHOI®/XibAU)qp9 
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Canvases 



Introduction 



Object 



QassCanvas 




QassBag 

QassControl 

QassSelectionList 



The NeWS canvas is a surface on which the PostScript language can be used to 
perform drawing operations. Canvases are arranged in a hierarchical manner, 
with the root being the device canvas or framebuffer. Both the shape and loca- 
tion of a canvas can be altered. While the default shape is rectangular, the 
News operator reshapecanvas will change the shape to match the region out- 
lined by the current path. 

The NeWS Development Environment's ClassCanvas combines a NeWS canvas 
object and an event manager process to create a self-sufficient user interface 
item. Examples of ClassCanvas subclasses span the range of simple user inter- 
face objects like buttons, sliders and scrollbars to more elaborate objects such as 
windows and menus. Even complete applications such as word processors and 
drawing editors are defined as a text canvas or a drawing canvas augmented by 
associated menus and property sheets. 

ClassCanvas itself is rather minimal, assuming that most interesting user inter- 
face objects will be created as subclasses. Qients creating such objects will 
therefore need to know the details of creating and designing a sul^lass of 
ClassCanvas. 

ClassCanvas instances are "smart NeWS canvases”, being able to manage many 
of the attributes of their NeWS canvas object. Thus they can paint themselves, 
repair their damaged areas, determine their shape, and map and unmap them- 
selves. In the following discussion, "canvas” is used to mean an instance of the 
Toolkit's ClassCanvas; using "NeWS canvas” to refer to the NeWS canvas object. 
Although is it useful to make this distinction in the following discussion, the 
NeWS canvas object is actually the same object as the ClassCanvas instance; this 
being done by adding the necessary keys to the NeWS canvas object to turn it 
into an instance. 
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Canvases can access their parent, sibling, and child canvases; providing the basis 
for a "container hierarchy". One particular ClassCanvas subclass, QassBag, 
relies on this capability to implement compound canvas instances such as win- 
dows, property sheets and command frames, all of which are composed of 
nested canvases. (See Chapter 4, "Managing Groups of Canvases" for informa- 
tion on ClassBag.) 

Certain attributes of canvases inherit through this container hierarchy rather 
than through the class hierarchy. For example, the FillColor, StrokeColor, and 
TextColor of canvas instances default to being their parent canvas'. 

A canvas can be either opaque or transparent. Drawing occurs on an opaque 
canvas that will also conceal the regions of canvases beneath it. You can draw 
to transparent canvas but anything drawn on a transparent canvas is painted on 
the first opaque canvas beneath it. A transparent canvas is used to define 
regions which are sensitive to input but do not interfere with drawing in other 
canvases. 

Canvas Creation & Destruction 

Canvases are created by calling /new with the parent canvas (either ClassCanvas 
instance or NeWS canvas object) as an argument. The canvas will be a created 
as a child of the given parent canvas. The initial values of several of the 
corresponding NeWS canvas attributes may be specified as class variables. Thus 
redefining the class variable /Transparent or /Mapped will change the initial 
value of the corresponding NeWS canvas. 

When a canvas is destroyed, it deactivates itself and tells the system to remove 
any references to it. References to the canvas that are not known by the canvas 
are presumed to be "soft" or under client control. The client must remove any 
reference to the canvas to complete the garbage collection of the canvas. The 
most obvious reference is the client handle to the canvas created during /new. 
Less obvious are references left on the operand or diet stacks. Similarly, the 
canvas cannot be the current canvas for any process. Reference "leaks" will be 
quite obvious: the canvas will not go away from the screen. (Note : /destroy 
does not unmap the canvas.) 
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Methods: 

/new 

/newinit 

/destroy 

/Retained 

/SaveBehind 

/Transparent 

/Mapped 

/EventsConsumed 



Canvas Appearance 

Canvases are responsible for their shape and graphical contents. The graphical 
contents of a canvas is determined by the /PaintCanvas method which defaults 
to using the values of several ClassCanvas class variables. The canvas is filled 
with FillColor, and the edge of the canvas is stroked with StrokeColor using a 
stroke width of BorderStroke. The colors may be manipulated with /setcolors 
and /getcolors. 

A TextColor and TextFont are also available for canvases containing text. The 
font is initialized from the parameters TextFamily, TextSize, and TextEncoding. 
The font may be manipulated by /settextparams, /textparams, /settextfont and 
/textfont. 

The /PaintCanvas method may be set using /setpaintproc. The procedure argu- 
ment will be method compiled, thus can contain "self” and "super" usage. Four 
utilities are provided for filling and stroking the canvas by the painting pro- 
cedure. 

/scroll provides a simple painting aid for scrolling. This procedure simply uses 
the News operator copyarea to displace the current contents of the canvas the 
desired amount, /scroll then calls /PaintScrolledArea which is generally over- 
ridden to be "smart." The default sets the clip path properly (even for oddly 
shaped canvases) and calls /PaintCanvas, 

Subclassers may override the default rectangular shape by overriding the /path 
method. This method simply takes a bounding box and creates a path just 
fitting that box. 
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Methods: 


/paint 


/PaintCanvas 


/setpaintproc 


/FillCanvas 


/setcolors 


/StrokeCanvas 


/getcolors 


/StrokeAndFillCanvas 


/settextparams 


/FillCanvasInterior 


/textparams 


/FillColor 


/settextfont 


/StrokeColor 


/textfont 


/BoiderStroke 


/scroll 


/TextColor 


/path 


/TextFamily 

/TextSize 




/TextEncoding 
/TextFont 
/Paints crolledArea 



Activation and Deactivation 

Each canvas has an associated event manager that may be activated and deac- 
tivated. Damage is handled by this event manager, as are the help facility and 
automatic menu management. 

When activated, a canvas uses its parent canvas' event manager if there is one, 
otherwise it creates its own. The canvas creates the interests it wants the event 
manager to manage in the /Makeinterests method (see chapter 7, "Interests”). 
These interests must contain their own callback; see the section "Executable 
Matches" in Chapter 7, "Interests." 



Methods: 




/activate 


/Makeinterests 


/deactivate 

/active? 

/eventmgr 


/CreateEventMgr 
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Canvas Damage Repair 

When the Retained attribute is true, the window system is requested to store a 
duplicate of the canvas pixels in memory. As the canvas suffers damage, the 
window system repairs the damage using the copy. The use of Retained is a 
hint which means that your /FaintCanvas or /FixCanvas method is not called. 

When opaque canvases are mapped, or when part of a canvas is exposed by 
moving a covering canvas, the canvas is sent a /Damaged event. The ClassCan- 
vas event manager responds to this event by calling the canvas' /HandleFix 
method. This method sets the canvas clip path, then calls the /fix method. 

(Note: the canvas clip is not the same as the clip path.) 

The /fix method checks to see whether the intersection of the canvasclip and the 
canvas is empty. If not, it calls the /FixCanvas method which defaults to 
/FaintCanvas. The test is made as a trivial rejection test to avoid unnecessary 
painting. 

Although the transparency of a canvas is set during initialization via the class 
variable /Transparent, it can also be dynamically changed using the /settran- 
sparent method. 

A sub-canvas of the opaque canvas handling damage may also desire forked 
painting. For example, in response to a menu command, the ’’client” tran- 
sparent canvas of an application may have to repaint itself. It may call /damage 
on itself; which will cause the event manager of the opaque parent to fork dam- 
age repair. 

When the SaveBehind attribute is true (the default for Toolkit menus), the win- 
dow system is requested to save pixels underneath this canvas when it is 
displayed. When this canvas is no longer displayed, the server should be able 
to repair the damage using the cached pixels. The SaveBehind attribute is use- 
ful for transitory canvases such as menus. It is also a hint. 



Methods: 


/fix 


/Transparent 


/settransparent 


/HandleFix 


/transparent? 


/FixCanvas 
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Help and Menus 

The default canvas event management also handles triggering a help procedure 
from the HelpKey, and popping up a menu from the MenuButton. 

When the HelpKey is pressed (as determined by the current UI), the HelpProc is 
called if non-null. This may be dynamically set using the /sethelp method, or 
can be set by the subclass via the /HelpProc class variable. Clients may cause 
the help proc to be executed directly through some alternative user interface by 
simply calling /callhelp. /help returns the current HelpProc. 

Similarly, if the MenuButton is pressed, the CanvasMenu is popped up and 
activated if non-null. The menu may be provided either by subclassers via the 
CanvasMenu class variable, or by clients via the /setmenu method. Menu call- 
backs generally will require the ClassTarget facility. If AutoTargetMenu is true, 
the canvas is installed as the menu's target just prior to popping up. 

Both help and menu may be set even after the canvas is activated; it will modify 
the running event manager properly. The same holds for damage discussed in 
the preceeding section. 



Methods: 


/sethelp 


/HelpProc 


/help 


/CanvasMenu 


/callhelp 


/AutoTaigetMenu 


/setmenu 




/menu 




/autotargetmenu 




/autotargetmenu? 





Canvas Tree Manipulation and Enumeration 

The News canvases are maintained in a tree rooted at the framebuffer. Because 
the NeWS canvas objects are identical to the ClassCanvas instances, the 
instances are automatically organized into a tree. (For an explanation of the 
difference between the canvas tree and the class tree see the NeWS Programmer's 
Guide.) The initial position of a canvas in the canvas tree is determined by the 
parent argument to /new. This can be changed using the /reparent method. 
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The canvas can change its location among its siblings using /totop and /tobot- 
tom. 

There are many enumeration procedures for retrieving canvases relative to the 
current canvas, /parent returns the parent canvas while /parents returns all par- 
rents to the framebuffer, /parentdescendant returns the first parent descending 
from a given class between the given canvas and the framebuffer, /parentdes- 
cendant is useful, for example, for a canvas to get its window frame: 

I 

All of a canvas' siblings, including itself, are obtained via /siblings+ and 
/siblings-; the "+" version being from back to front. A list of a canvas' siblings 
above or below but, not including itself, is obtained by using /siblingsabove or 
/siblingsbelow. A list of all my children is obtained by /children+ or 
/children-; the "+" & as with siblings, /descendants returns all canvases 
below me, including me. 

For performance reasons, these lists do not check that the canvases are true 
instances. To remove non-instances from an array, use /FilterNonInstances. 

The canvas tree is used to implement a container hierarchy. An object is said to 
inherit through the container hierarchy if it includes a class variable that 
defaults to its parent's value. Thus the colors all inherit though the container 
hierarchy. This is logical: it makes more sense for a color to default to its 
parent's value than its superclasses. 



Methods: 


/new 


/siblings- 


/reparent 


/siblingsabove 


/totop 


/siblingsbelow 


/tobottom 


/children+ 


/parent 


/children- 


/parents 


/descendants 


/parentdescendant 


/FilterNonInstances 


/siblings-i- 






Canvases 



3-7 







Canvases 



Canvas Geometry 

The canvas may be reshaped or moved to change its size or location. Reshaping 
is done by specifying a bounding box; the canvas will reshape itself, using /path, 
to just fill that blwx. You move a canvas by specifying the position of the lower 
left comer of its bounding box. Both operations specify their coordinates using 
the CTM (current transform matrix). This means that whatever scale, rotation, 
and translation is in effect will be used during the reshape or move. 

This use of the CTM is vital to the flexibility of the NeWS Development 
Environment. It allows a vertical scrollbar to be made from a horizontal 
scrollbar by simply rotating the CTM before placing it. It allows scaling of an 
entire application by reshaping its window with the CTM scaled. It allows nest- 
ing of windows within other windows because they do not assume they are 
positioned relative to the framebuffer. 

Each NeWS canvas object has its own coordinate system; that which is in effect 
when "reshapecanvs” is called. This defines the CTM established each time 
"setcanvas” is called. The NeWS Development Environment has adopted the 
protocol that both /reshape and /move specify their coordinates relative to the 
bounding box with orgin at the lower left comer. The canvas itself may use any 
scale, and even translation it likes. It must, however, return the /size, /location, 
and /bbox in the caller's CTM with a lower-left origin. 

To help with separating the caller's coordinates and the canvas' coordinates, the 
Transform utility tranaslates from the callers space to the canvas'. This defaults 
to a simple translate to the caller's lower left comer. It is commonly overriden 
to give ^e canvas a 0-1 coordinate system to simplify calculations: 

f ^ 

/Transform {^xy%rh->00XX 

4 2 roll % w h X y 

translate scale % - 

0 0 1 X 

} daf 

V J 
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In sum, the caller "owns” the positioning and size of the canvas in whatever 
CTM desired; the canvas itself "owns" its default (private) CTM. 

Canvases typically manage data which imposes size constraints on the canvas. 
The canvas should not be sized below its /minsize. The canvas might also have 
a /preferredsize somewhat greater than that size. Thus a text editor n\ight 
choose to display at least one line of 20 characters as its minsize, but choose a 
preferred size of 80 characters by 40 lines. The /reshape method does not 
inforce the minsize limit. This must be done by the client. This is done to 
avoid unnecessary checking that the client can more easily do. Typically the 
client will "know" enough of the semantics of the application canvas layout to 
impose these limits in a simple manner, /lockminsize may be used by a client 
to install a simple, constant, non-calculated, minsize in a canvas after perform- 
ing the calculation the first time. 



Methods: 


/reshape 


/Transform 


/move 


/lockminsize 


/size 


/preferredsize 


/location 




/bbox 




/minsize 





User Interaction Utilities 

ClassCanvas provides simple user interaction methods with reasonable default 
bahavior. These procedures are based on the "getfromuser" utility (triggered on 
UpTransition) and use the /path method to provide reasonable default ^havior. 

The utilities are typically called after a DownTransition has been processed, 
often in an interest provided in the canvas' Makeinterests. The following would 
provide trivial dynamic resizing and moving of the associated canvas: 
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A6*®Int«est8 <%-->• InteiMtllst 
/KafceXntdrd 5 t» smd 

/LeftMQU9eButtOQ (pop ^npv0fxoR«9Or| 
/PowTrsnaition Canvas MakeXnt«W9»t 
/MiddleMoiiseBotton /sttetchcOiA^ 
/DQwnTran^itioQ Canvas liakoInt^r99t 

) daf 



Methods: 

/stretchcomer 

/bboxfromuser 

/reshapefromuser 

/movefromuser 



Canvas Validation 

To help optimize flicker-free, high performance re-painting of canvases after 
changes to their contents, QassCanvas supports a simple validation scheme. 
When changes are made to a canvas that cause its image to need updating, the 
canvas is sent /invalidate. When the canvas next is told to paint itself, it first 
checks to see if it is valid. If not, it sends itself the /validate method. Note that 
several invalidations may be made without causing the repaint to occur. 

/validate should be overridden to change any internal parameters of the canvas 
required by the PaintCanvas routine. ClassBag, for example, will call its /layout 
method from /validate. 



Methods: 

/invalidate 

/validate 

/valid? 

/?validate 
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Canvas Cursors 

ClassCanvas supports defaulting the cursor associated with a canvas, and set- 
ting this cursor interactively. This facility attempts to use shared ’’well known" 
cursors; cursors whose name is known to the system. Generally subclassers 
simply define the class variable /Cursorlmage to be a well known cursor name. 
The CursorMask is assumed to be the next glyph in the cursor font; set it to a 
non-null value to override this assumption. Use the /setciursor method to use 
any non-shared cursor you might need. The names of the NeWS Development 
Environment's cursors are: 



/basic 


/panning 


/rtarr 


/move 


/navigation 


/xhair 


/copy 


/nouse 


/xcurs 


/busy 


/ptr 


/hourg 


/stop 


/beye 





Methods: Subclassing Methods: 

/setcxursor /Cursorlmage 
/Ciu-sorMask 



Canvas Focus Management 

For an explanation of Focus Management see Chapter 4, Managing Groups of 
Canvases, section "Focus Management." 
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3-11 






4. MANAGING GROUPS OF CANVASES 




Managing Groups of Canvases 



Managing Groups of Canvases 


4-1 


Introduction 


4-1 


Bags 


4-1 


■ Creation and destruction 


4-2 


■ Insertions and Removals 


4-3 


■ Access to Bag Clients 


4-5 


■ Graphics State Utilities 


4-6 


■ Sizing Protocols 


4-6 


■ Layout and Invalidation 


4-7 


■ Activation and Event Management 


4-8 


■ Painting and Damage Repair 


4-9 


Containers 


4-10 


■ Client Naming 


4-10 


■ Creating a Container 


4-10 


■ Getting and Setting the Ciient 


4-11 


■ Size Negotiations 


4-12 


OpenLookPane 


4-13 


■ Controlling the Scrollbars 


4-13 


Frames 


4-14 


■ Frame Attributes 


4-15 


■ Opening, Closing and Zooming 


4-16 


■ Manipulating a Frame Menu’s Default Behavbr 


4-17 


■ Subframes 


4-18 


■ Notification 


4-19 


■ Selection and Focus 


4-20 


■ Freezing 


4-20 


■ /demo Method 


4-21 


■ Frame Class Hierarchy 


4-21 


■ OPEN LOOK Frames 


4-22 


■ Frame Size and Placement 


4-23 


■ Subframe Functions 


4-23 


■ Shared Frame Menus 


4-24 


■ Instantiating Frames 


4-24 


■ Subclassing Frames 


4-24 


■ Adding Frame Attributes 


4-26 


Table of Contents 


1 









Table of Contents 



Utility Bags 


4-28 


■ AbsoiuteBag 


4-29 


■ RowColumnBags 


4-31 


■ Rex Bags 


4-32 


Example of Bag Usage and Subclassing 


4-35 


Focus Management 


4-39 


■ Focus Definitions 


4-40 


■ Focus Forwarding 


4-41 


■ Focus Noticing 


4-41 


■ How Focus Forwarding and Noticing Works 


4-42 



II 



tNt Technical Reference Manual 




Managing Groups of Canvases 

Introduction 

A bag is a canvas that is designed explicitly to manage a group of 'child' NeWS 
Development Environment canvases. (See the NeWS Programmer's Guide an 
explanation of the parent/child relationships in the NeWS canvas hierarchy.) 
ClassBag is the basis for many of the NeWS Development Environment's com- 
ponents — frames are bags, panes are bags, an application's control area will 
typically be a bag of control canvases. Whenever a group of canvases are 
brought together to achieve some effect, a bag will manage them. 



Figure 4-1: Bags 



QassCanvas 
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RowColumnBag 

ClassContainer 
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Bags 

As an intrinsic class ClassBag is rarely instantiated directly. It is designed 
expressly for subclassing. ClassBag extends the NeWS canvas hierarchy model 
in the following important ways: 

■ Child canvases (called 'clients' of the bag) can be given names when they 
are added to the bag. These names may be used later to refer to these can- 
vases. This feature obviates the need for application programs to hold 
references to every canvas in their application. 

■ Instances of any subclass of ClassGraphic (commonly referred to as 
'graphics') can also be managed as clients of the bag. 

■ Bags explicitly manage the layout of their clients. Different bags have dif- 
ferent layout policies, but ClassBag controls when the layout procedure is 
activated. Because the NeWS Development Environment assumes that 
layout may be an expensive operation, bags minimize the number of times 
the layout procedure is called by the use of a validation scheme. 



Managing Groups of Canvases 



4-1 




Managing Groups of Canvasss 



■ Bags manage the sharing of event n\anagers. In a t)^ical toolkit applica- 
tion there is one event manager process watching for mouse actions and 
keystrokes for each frame in the application. Via its activation and deac- 
tivation primitives, ClassBag allows every canvas in a frame to share the 
same event manager. 

■ Bags manage the damage repair for their transparent child canvases. This 
effectively means that most canvases inside a frame can be transparent, 
and a significant space improvement can be gained over using opaque 
canvases. The bag will also take care of painting the graphics they 
manage when damage occurs. This allows graphics to be treated as light- 
weight canvases which are not sensitive to input. 



Creation and destruction 

Like all canvases, bags expect a canvas object to be on the top of the stack when 
/new is called. This canvas becomes the parent of the newly created canvas. 
There is no requirement that the parent of a bag be another bag. 

When /destroy is sent to a bag it also sends /destroydependent to each of its 
clients. This defaults to sending /destroy to them. Whole bag hierarchies can be 
destroyed in this way. Frames for example will destroy all their ornaments and 
their client subtree when /destroy is sent to them. 

If you wish to prevent some client of a bag from being destroyed when the bag 
is destroyed, you should override the client's /destroydependent method, and 
not allow it to default to /destroy. Canvases that are still bag clients after /des- 
troydependent is called are reparented to an offscreen canvas so that the bag 
can be disposed of completely. 

Methods: 

/new 

/newinit 

/destroy 

/destroydependent 
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Insertions and Removals 



The /addclient method is used to insert a canvas or a graphic into a bag. (See 
section 2 on ClassBag for a detailed explanation of the syntax of /addclient.) 
There are three independent choices to make when adding a client to a bag. 



1 . The client may be an instance or a class. If the client is ClassCanvas or 
any subclass of ClassCanvas then the class itself may be used as an argu- 
ment to /addclieni For other classes (e.g., ClassGraphic) /addclient must 
be given an instance. Given a class, the bag will send /new to the class to 
obtain the instance. Adding clients as classes is slightly faster (NeWS 
does not have to reparent the client canvas) and more compact than 
preinstantiating them. If a class is supplied, then the application must 
also provide arguments for the later instantiation of the class. For exam- 
ple, the above bag insertion could be done using the class OpenLookBut- 
ton in the following way: 






[aO 50 (Poo> {button-c^lbacK) OpenLookButton] /addclient mybag send 



The button's label and callback are the arguments that will be handed to 
/new by the bag in this example. (A parent canvas argument is not pro- 
vided with the class because the bag itself will become the parent of the 
newly created canvas.) The /NewClient method is used to instantiate 
clients when a class is added. /NewClient defaults to calling /newdefault 
on the class. 

2. A client may or may not be named. If a name is provided for /addclient 
the client can be retrieved later by providing the same name to /get- 
byname. If 'null' is given as a name for all bag clients, then bags save 
space by not maintaining the name/client mapping. Access the clients by 
insertion order in this case. For example, '0 /getbyname bag send' 
returns the first client inserted in the bag. 

3. A client may or may not have "baggage.” Baggage is unformatted infor- 
mation used by subclasses of ClassBag. Typically it provides layout infor- 
mation to the subclass. For example, an AbsoluteBag requires U\at two 
numbers (the x,y coordinates) be provided as baggage when adding a 
client. These numbers get wrapped in an array along with the instance: 
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When adding a client to a subclass that does not require baggage (for 
example RowColumnBag), the array is not required: 




Sophisticated subclasses that wish to change the way client references are 
maintained by the bag may override /RegisterQient and /DeRegister- 
Client. For example, if an application is keeping references to every client 
of the bag via some external mechanism the application can prevent the 
bag from duplicating this effort by overriding these methods and provid- 
ing its own /clientlist method. 



To remove a client from a bag use /removeclient. This method expects an 
integer (if the client was added with a null name), or the client itself as argu- 
ments. To move an object from one bag to another it must first be removed 
from the first, and then added to the second. 

Methods: 

/addclient 

/removeclient 

/getbyname 

/NewClient 

/RegisteiClient 

/DeRegisterClient 
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Access to Bag Clients 

There are a number of methods for interacting with the clients of a bag. 

/b^^ggage and /setbaggage can be used to retrieve and modify the subclass- 
specific information passed in during /addclient. Bag layout procedures for 
example, usually call /baggage on each client to get their layout information. 

The number of clients is returned by /clientcount The set of clients is returned 
as an array by /clientlist /graphicclientcount and /graphicclientlist provide the 
same information, but only for those clients that are graphics. To retrieve the 
list of clients that are canvases, use the ClassCanvas meAods /children+ or 
/children-. 

An arbitrary object can be presented to /client?. A boolean is returned; it indi- 
cates whether or not this object is a client of the bag. Note that the bag does 
not maintain a reverse index from objects to names. Given an object that is 
known to be in the bag there is no way to find out what name was specified for 
it during /addclient 

A convenience wrapper around /clientlist is /foreachclient. It takes a procedure 
and foralls it over the list of clients, /sendclient sends a method to a named 
client of the bag. For example, to change the label on the button in the previous 
example call: 

/aotlaboX /bl /a^cUent bag 9<and 
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Methods: 

A)aggage 

/setbaggage 

/client? 

/clientcount 

/clientlist 

/graphicclientcount 

/graphicdientlist 

/children+ 

/children- 

/foreachclient 

/sendclient 



Graphics State Utilities 

When subclassing a bag it is often desirable to establish the bag's canvas as the 
current canvas. This is especially true when measuring the size of a bag client, 
or laying the bag out. ClassBag provides two utilities, /BagBegin and /BagEnd 
which it uses internally to set and restore the graphics state for this purpose. 
Certain subclasser methods are called from within a /BagBegin /BagEnd context, 
and it is important to take advantage of this so that the subclasser doesn't dupli- 
cate the effort. The methods /Layout, /Minsize, /PreferredSize are currently 
treated this way. Each will be discussed below. 

Methods: 

/BagBegin 

/BagEnd 



Sizing Protocols 

ClassCanvas establishes two important sizing interfaces: /minsize and /pref er- 
redsize. ClassBag turns these into protocols by making them hierarchical: most 
bags when sent /minsize ask their clients the same question, and use the results 
to calculate their own answer, /preferredsize works in the same way. 

ClassBag cannot perform this recursive /minsize (or /preferredsize) calculation 
itself. It does not know how to combine the various answers it would get. 
Subclasses of ClassBag do have this knowledge however, and are expected to 
take their clients into account when calculating /minsize or /preferredsize. For 
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example, the /minsize for ClassContainer asks /minsize of its main client, then 
adds a pair of constants to leave room for the borders of the container. 

If the minimum size calculation for a subclass of ClassBag does not require that 
the bag be established as the current canvas, then you can override /minsize 
directly. If an application requires that the bag be the current canvas it should 
override /MinSize. In /MinSize one can assume that the graphics state has 
been set up correctly. The same applies for /preferredsize and /PreferredSize. 

Methods: 

/minsize 

/MinSize 

/preferredsize 

/Preferredsize 



Layout and Invalidation 

ClassBag uses the term 'layout' to mean the jx)sitioning (and perhaps resizing) 
of bag clients once the size and shape of the bag itself has been established. 
Performing layout, by overriding the /Layout method, is the responsibility of all 
subclasses of ClassBag. The bag will be the current canvas when /Layout is 
called, so it is the job of the subclasser to /move or /reshape each client of the 
bag to take advantage of the current /size of the bag. 

Applications do not normally call /layout (which calls /Layout inside a /BagBe- 
gin, /BagEnd pair) themselves. Instead, each bag maintains a 'valid' flag which 
it uses to decide whether layout is necessary. This flag is checked as the first 
phase of both /paint and /fix. If the layout has been invalidated, /layout is 
called before painting begins in earnest. The methods which automatically 
invalidate the layout are: /reshape, /addclient, and /removeclient An applica- 
tion that does not wish to have the layout invalidated when any of these 
methods are called, should override /?invalidate. To manually invalidate the 
layout (perhaps because the geometry of one of the clients changed in some 
way), applications should call the bag's /invalidate method. 

Most applications that use bags will never call /layout, /validate, /?validate, 
/invalidate, /?invalidate, or /valid?. They will simply override /Layout and rely 
on the validation protocol to call this method when layout is required. 
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Methods: 

/layout 

/layout 

/?validate 

/?invalidate 

/invalidate 

/valid? 

/validate 

/reshape 



Activation and Event Management 

ClassBag plays an important role in the event management for a hierarchy of 
canvases. The QassCanvas /activate is responsible for searching up the canvas 
hierarchy looking for an already active canvas (one that has an event manager 
process handling it). If it fails to find an event manager /activate will create 
one. After an event manager is found or created, the canvas's /Makeinterests 
method is called and the resulting interests are expressed in the event manager 
process. 

ClassBag overrides /activate and augments the QassCanvas' /activate by recur- 
sively cdling /activate down the tree on its client canvases. The upshot of this is 
that a single /activate method sent to the root of a bag hierarchy causes every 
canvas in the tree to become active. All their interests are expressed in a single 
event manager process created at the root of the tree. In particular, to make 
every canvas inside an application's frame sensitive to input, it suffices to send 
/activate to the frame. 

/deactivate undoes the effect of /activate. It removes the interests for every can- 
vas in the bag hierarchy rooted at the canvas to which the method was sent. It 
then kills the event manager process if this process was created expressly for the 
given bag. 

/active? returns true if there is an event manager process alive and fielding 
events on this canvas. 

Removing a client from the bag (via /removeclient) causes it to be deactivated if 
and only if it shares an event manager with the bag. In practice this means that 
if an application activated a client before putting it into the bag the client will 
still be active after removing it from the bag. 
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Methods: 

/activate 

/deactivate 

/active? 



Painting and Damage Repair 

ClassCanvas establishes simple interpretations for /paint and /fix. /paint is 
called by the application to manually refresh a canvas. When NeWS generates a 
/Damage event /fix is called to repaint some damaged portion of a canvas. 

ClassBag extends these methods by making them recursive. The /paint method 
sent to a bag not only paints the bag's canvas (by calling its /PaintCanvas 
method), but also calls /paint on its mapped child canvases, using /PaintChil- 
dren. A bag's /paint method also has the responsibility for painting the graphic 
clients of the bag and does so by calling /PaintGraphicChildren. The recursive 
nature of ClassBag's /paint is responsible for the fact that a /paint sent to a 
frame will refresh every canvas inside the frame. 

The /fix protocol is a little more complex because NeWS distributes /Damage 
events only to the opaque canvases in the damaged area. The /fix method in 
ClassBag only takes responsibility for recursively fixing those child canvases 
that are transparent. /FixChildren propagates /fix down the tree, and /PaintGra- 
phicChildren is still called on each bag encountered in the recursion. The end 
result is that /FixCanvas is called once for every canvas inside or overlapping 
the damaged region. 



Methods: 


/paint 


/FixChildren 


/fix 


/PaintChildren 


/FixCanvas 


/PaintGraphicChildren 


/PaintCanvas 
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Containers 

A container is a kind of bag that is specialized to handle one ntajor client, and 
zero or naore nainor ones. Usually the nainor clients are allocated a fixed amount 
of real estate in the bag, and the major one grows and shrinks as the bag 
changes size. 

ClassContainer is not designed to be instantiated directly. It is subclassed within 
the toolkit, and these subclasses are themselves instantiated. 

Frames are the most important subclass of containers. The major client of a 
frame is the canvas that occupies the interior of the window. The minor clients 
are the ornaments (resize corners, close box, footer, etc.) that surround the win- 
dow interior. When a frame is reshaped the minor clients are moved to new 
positions on the edge of the frame, and the major client is reshaped to take up 
all the remaining area. 

Because of its special significance the major client of a container is often referred 
to simply as 'the client' of the container. Hence we often refer to the interior 
canvas of a frame as 'the client of the frame'. 

Client Naming 

ClassBag leaves the business of associating a name with each client up to the 
application. ClassContainer restricts client naming in the following important 
way; the major client of a container always has the name '/Qient'. This is in 
fact how ClassContainer distinguishes the major client from the others. When 
adding minor clients to a container, you may give them any name other than 
/Client. 

Creating a Container 

Containers expect the major client to be presented as an argument to /new when 
creating an instance of some subclass of ClassContainer. In common with 
ClassBag's /addclient syntax, this client argument may be either an instance, or 
an array containing a class and the arguments requir^ to instantiate that class. 
For example, there are two ways to create a frame containing a vanilla 
ClassCanvas instance: 
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frmeSo^ttex /mv Cl^aoCmvM «end 
n framabuffar /naw OpenLookBaseFri^ send 



in which an instance of the canvas is handed in, or 



[ClaasCanvas] t] fraro^uffar /new OpenLoQkBaaeFxame aend 



in which a class is handed in, and the container automatically instantiates this 
class. The second version above is not only more terse, it is also more efficient. 
The client canvas does not need to be reparented from the framebuffer. It is 
created with the container as its parent. 

It is also legal to present 'null' as the client argument when instantiating a con- 
tainer. Until set otherwise such a container will have no client whatsoever. 



Methods: 

/new 

/newinit 



Getting and Setting the Ciient 

The major client of a container can be changed at any time by calling /setclient 
on that container, /setclient returns the previous client (if any) of the container. 

This current client is returned by the method /client (Note that /client is just a 
thinly veiled call to /getbyname using the /Qient name.) 
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Methods: 

/setclient 

/client 



Size Negotiations 

Containers maintain four class variables to help position the major client inside 
the container. These are the (usually constant) amounts of border space to leave 
to the top, right, bottom and left of the major client when laying it out. The 
method /BorderWidths sums up the left and right borders, and /BorderHeights 
sums the top and bottom space. 

/fitclient takes a proposed client size, and returns the total size of the container 
necessary to give the client the specified width and height, /unfitclient does the 
reverse. It tells you how big the client will become if the container is reshaped 
to the given size. Both these methods make use of /BorderWidths and /Bor- 
derHeights. 

The /minsize of a container is the /minsize of the major client added onto the 
size of the borders. Similarly, the /preferredsize of the container is the /prefer- 
redsize of the client plus the size of the borders. 



Methods: 


/fitclient 


/BorderLeft 


/unfitciient 


/BorderBottom 




/BorderRight 

/BorderTop 

/BorderHeights 

/BorderWidths 
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OpenLookPane 

OpenLookPane is a subclass of ClassCoi\tainer whose job is arrange either one 
or two scrollbars around some canvas. This canvas is the major client (named 
/Client) of the container, and will presumably be manipulated by the scrollbars. 

The scrollbars are not automatically connected to the client canvas. To use an 
OpenLookPane you must not ordy provide a client canvas, but also provide the 
cdlbacks for the scrollbar(s) to update it. (See Chapter 6, Controls, the ScrollBar 
section.) 

Controlling the Scrollbars 

The class variables /UseHSbar? and /UseVSbar? control whether or not the 
pane, when instantiated, will have a horizontal and/or a vertical scrollbar. Verti- 
cal scrollbars appear to the right of the client canvas, horizontal ones to the bot- 
tom. 

The subclasser methods /CreateVerticalScrollbai and /CreateHorizontal- 
Saollbar by default return instances of OpenLookVerticalScrollbar and Open- 
LookHorizontalScrollbar respectively. You should override these if you have 
your own scrollbar that you wish the pane to use. 

The subclasser methods /CreateHSbarNotify and /Create VSbarNotify return the 
notification procedures for the scrollbars. Override these methods to make your 
scrollbars control your client canvas. 

Methods: 

/CreateVerticalScrollbar 

/CreateHorizontalScrollbar 

/CreateHSbarNotify 

/CreateVSbarNotify 



Class Variables: 

UseHSbar? 

/UseVSbar? 
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Pane Sizing 

The /minsize of a pane is the maximum of the /minsize of the client canvas and 
the minsize of whichever scrollbars happen to be present. Currently there is no 
analagous calculation for the /preferredsize of an OpenLookPane. The /prefer- 
redsize thus defaults to the pane's /minsize. 

Methods: 

/minsize 



Figure 4-2: Frame Hierarchy 



aassContainer— ^ 



QassFrame 




ClassBaseFrame 
ClassCommandFram& 
ClassHelpFrame 
OpenLookFrame 
ClassIconFrame 
ClassNoticeFrame 
ClassPropertyFrame 




OpenLookBaseFrame 

OpenLookCommandFrame 

OpenLookHelpFrame 

OpenLookIconFrame 

OpenLookNoticeFrame 

OpenLxx)kPropertyFrame 



Frames 

ClassFrame implements window frames. It is an intrinsic class that provides a 
set of protocols and utility methods that are useful for many different types of 
windows. As an intrinsic class, QassFrame is not intended to be instantiated 
itself. Instead it provides a framework on which to build subclasses that can be 
instantiated. OPEN LOOK frames are the classes meant to be instantiated. 

A frame manages a single "client" canvas. The frame wraps that canvas with a 
border that may include various ornaments irtanaged by the frame. Examples 
of ornaments are a title area, reshape controls, close or grow boxes, etc. 
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A frame has a number of attributes, e.g. "is it reshapeable?”, or "can it be 
closed?" There will be some visual indication of these attributes, often in the 
form of some ornament, e.g. a control or graphic. Or, there may be a menu 
item corresponding to the attribute. ClassFrame defines a minimal protocol for 
these attributes, but leaves the implementation of ornaments or menu choices to 
subclasses. The frame is a bag, so the subclass may use it to hold any orna- 
ments. 

A frame can have associated with it some number of secondary frames, known 
as "subframes". ClassFrame defines an icon to be a standard subframe, but 
leaves the creation of an icon to subclasses. Other subframes may be added by 
subclasses. ClassFrame provides mechanisms for managing the list of subframes 
and ways to send messages between superframes and subframes. 

Other intrinsic frame facilities include the ability to be selected and to have the 
input focus, notification of the client when the frame's state changes as the 
result of a user interaction, temporarily freezing processing of events, opening 
and closing (i.e. unmapping a frame and mapping its associated icon frame), 
zooming the frame to a larger size, and restoring ("unzooming") it to its normal 
size. 

Frame Attributes 

A frame has a set of attributes, each having a name and a boolean value. The 
standard set of attributes for ClassFrame are: 



/Qose 

/Footer 

/Label 

/Pin 

/Reshape 



True to allow closing the frame to an icon 

True to display a footer area 

True to display a label (title) area 

True to allow the frame to be pinned (stay up) 

True to allow the frame to be reshaped 



The attributes usually correspond to some sort of control, e.g., a close box or 
label (title) area. The attributes are known outside the frame by their names, 
e.g., /Label. Each attribute has a default value specified by the frame subclass. 
These default values n\ay be overridden for a particular frame instance with a 
parameter to /new when the frame is created. You may query or change the 
attributes for an existing frame with the /frameattribute and /setframeattribute 
methods. 
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The implementation and behavior of frame attributes is entirely up to frame 
subclasses. A client user of a frame should make no assumptions about how the 
attributes are displayed to the user or how they are implemented. A typical 
implementation by a subclass is to create a control corresponding to an attribute 
and to put the control in the frame's bag. Or, a subclass may use an attribute to 
enable or disable an item on the frame's menu. Another possibility is to use the 
attribute simply to enable or disable some feature of the frame with no visible 
indication, e.g., the /Reshape attribute could simply allow a frame to be 
reshaped when the user presses a mouse button on part of its border. 

Each of the standard attributes has several related methods. For example, the 
/Footer attribute has methods /setfooter and /footer to set and retrieve the 
footer messages for the frame. 

Additional attributes may be defined by subclasses. 

Methods: 

/new 

/frameattribute 

/setframeattribute 

/footer 

/setfooter 

/label 

/setlabel 



Opening, Closing and Zooming 

An intrinsic notion of frames is that they may be closed to an icon, zoomed to a 
larger size, and opened or unzoomed back to their normal size. An icon is a 
subframe with the predefined name /Icon. When a ft-ame is closed, it is 
unmapped and its icon subframe, if present, is mapped. Icons may be any size 
or shape, and may display any image. When a frame is zoomed, it is reshaped 
to a larger size. By default, the larger size is the width of the unzoomed win- 
dow and the height of the framebuffer. 
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Methods: 

/open 

/opened? 

/flipiconic 

/zoom 

/zoomed? 

/flipzoom 



Manipulating a Frame Menu’s Default Behavior 

You can intercept common user-issued window commands such as refresh, 
zoom, close (iconicize), reshape and quit. The next five subsections explain the 
methods you can use to change the toolkit's default actions for these commands. 

The client canvas of a frame will be stretched to take up the available space 
automatically when the frame is reshaped. If this is not the behavior you desire 
you can override the client's /reshape method. 

In order to constrain the way in which a frame can be reshaped, several options 
are available. One way to prevent reshaping altogether for a time is by dynami- 
cally adding and removing the resize-corners via the /setframeattribute method 
(see below). To prevent a frame from being made smaller than some size, 
specify a minsize for your client canvas (or the frame itself). Even more com- 
plex nondefault reshape behavior is possible by overriding the frame's /reshape 
method. For example if you wanted a frame with dimensions that were always 
some multiple of 10 points the override to /reshape would be: 



/reshape { % x y w h -> - 

10 4±v round 10 mul exoh 
XO div round 10 ml exch 
/reshape super send 

v J 

This would change the width and height arguments before executing the default 
reshape action. 
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Refresh 

Some applications may wish to be infonned that "refresh" was called from the 
frame menu (as opposed to a normal damage event). For example, calling 
refresh from the window menu might cause the client to reprocess some data 
file rather than just initiate a repaint. This behavior can be achieved by overrid- 
ing the /paint method. When a frame receives explicit refreshes (like ttiose 
called ft'om the frame menu) /paint is called. Thus to change the behavior of 
explicit refreshes /paint must overridden. 

Iconicize 

Some users may want to know when a window is iconicized. For example, a 
game may want to suspend the game clock until the window is reopened. To 
achieve this and similar behavior, override /open, /open takes a boolean argu- 
ment, false for iconifying the frame, true for deiconifying it. 

Zoom 

Override /zoom to implement changes to a frame's behavior when Zoom is 
selected from the frame menu. Like /open, /zoom takes a boolean argument. 

Quit 

You can interpose on "Quit" by overriding /destroyfromuser in the frame. This, 
in turn, overrides the quit sent from both the frame and icon menus. For exam- 
ple, if an application wanted to put up a confirming notice before the quit was 
executed /destroyfromuser would be overridden to show it. The callback from 
the confirming button would send the destroy method to the frame. 

Subframes 

A frame (the "superframe") may manage one or more subframes. ClassFrame 
defines the following behavior for subframes: 

■ Destroying a superframe destroys its subframes. 

■ Subframes share the event manager of their superframe. 

■ Activating/deactivating a superframe does the same for its subframes. 

■ Freezing/unfreezing a superframe does the same for its subframes. 
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A frame has a dictionary of its subframes, so each subframe has a name associ- 
ated with it. The subframe list is managed with the /addsubframe and /remo- 
vesubframe methods. Each subframe has a reference to its superframe, accessed 
with the /superframe method. Subframes may be nested more than one level 
deep. 

Methods: 

/addsubframe 

/removesubframe 

/subframe 

/subframe? 

/subframes 

/superframe 

/rootframe 

/sendsubframe 

/sendsuperframe 



Notification 

Frames provide a notification mechanism similar to that of controls. The client 
application may provide a notification procedure, using /setnotifyproc, that will 
be called whenever the state of the frame changes as the result of a user interac- 
tion. The notify proc can obtain the reason for the notification via the 
/notifyreason method. 

Currently only a small number of interactions cause notification to happen. 
These are: 



Reason 


Interaction 


/NotifyPin 

/NotifyProps 

/NotifyReset 

/NotifyApply 


Frame pinned /unpinned 
Property sheet brought up 
Reset chosen in the property frame menu 
Apply chosen in property frame menu 



The above four names are the values obtained from a call to the /notifyreason 
method from the frame's notify proc. The notify proc is set via /setnotifyproc. 
This simply means that some event occurred, e.g., a frame was unpinned. You 
can do something when you are notified that the event occurred or you can 
ignore it. 
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Methods: 

/setnotifyproc 

/notifyproc 

/setnotifyreason 

/notifyreason 

/callnotify 



Selection and Focus 

A frame may be selected or given the input focus. Typically this will be done 
automatically by selection and focus managers. Frames have methods to give 
visual feedback that they are selected or have the focus. 

Methods: 

/reflectfocus 

/reflectselected 

/setfocus 

/focus? 

/setselected 

/selected? 

/selectedframes 

/notifyselected 

/sendselected 



Freezing 

A frame may be "frozen", i.e., made to ignore most events. Typically a frame is 
frozen because the user is being noticed of a situation such as an error and 
must give some input before the application can proceed. When a frame is 
frozen, the only events it processes are those for damage repair and loss of focus 
or selection. A frozen frame is not the same as the OPEN LOOK UI Specification 
defines as busy. 
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Methcxls: 

/freeze 

/freezeall 



/demo Method 

ClassFrame includes a /demo method that can be sent to any derived subclass. 
The method sends /new to the class to which /demo was sent. Examples: 

I Il l 

/<|QmQ OpenLookHalpFravn^ 9^ 

/demo Oponlook&aBePramd stand 

V ^ J 

Frame Class Hierarchy 

There are six intrinsic frame types, defined in subclasses of QassFrame: 

ClassBaseFrame 

ClassCommandFrame 

ClassHelpFrame 

ClassIconFrame 

ClassNoticeFrame 

ClassPropertyFrame 

These classes do not provide any additional functionality beyond that provided 
by ClassFrame. These classes exist to be abstract sup>erclasses that have 
corresponding look and feel classes, such as OpenLookBaseFrame. These classes 
will tj^ically be used as follows. By a client: 

( 

<paramotors>- /new OpenLookBaseFrame 

V 
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By a subclasser; 




/^BaseFrarne /defaultclass ClassBaseFraine aeaid (] 
claaabegin 



^^^claaaend def y 



ClassFrame contains behavior that is shared by all frame types. The frame type 
classes contain behavior that is particular to the specific types. You should sub- 
class ClassFrame to define data and methods that are shared by more than one 
frame type. You should subclass the frame type classes, mixing in your subclass 
of ClassFrame, to define the individual frame types. In many cases a particular 
behavior will be shared by most frame types but for one frame type it will be 
different. Use the class hierarchy to implement this - define the common 
behavior in your ClassFrame subclass, then override the appropriate methods in 
the class for the different frame type. This is preferable to having a single 
shared method that has conditional code based on frame type. 

OPEN LOOK Frames 

Class OpenLookFrame is a subclass of ClassFrame that implements functionality 
shared by OPEN LOOK frame types. The six OPEN LOOK frame types are 
implemented as subclasses of the six intrinsic frame types. Multiple inheritance 
is used to give each of these classes two superclasses: the intrinsic frame class 
and class OpenLookFrame. OpenLookFrame implements appearance and 
behavior that is shared by all the OPEN LOOK frame types. The class, and 
several helper classes, implements the frame label, footer, reshape corners, menu 
button, etc. These ornaments correspond to the frame attributes, e.g., /Reshape, 
/Footer, defined in ClassFrame. OpenLookFrame also includes the following 
features that are shared among more than one frame type including OpenLook- 
BaseFrame. Behavior that is particular to one frame type is typically imple- 
mented in that type's subclass. 
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Frame Size and Placement 

Like all canvases, frames have the notion of a preferred size. By default a 
frame's preferred size is a frame large enough to display its owner, label, and 
footer in their entirety. Frames also display their clients at the clients preferred 
size. To change this default, override /preferredsize. 

The /place method computes a default size and placement for a frame. If the 
frame has already has b^n reshaped that size is preserved and the frame is 
only moved in response to a place message. If the frame has a superframe (see 
below for an explanation of superframes) it is positioned so its upper left comer 
is coincident with the upper left comer of the super frame. If the frame doesn't 
have a superframe (as most base frames don't) then the frame is positioned suc- 
cessively down the diagonal of the screen starting at the upper left comer. 

If the frame has not been shaped yet (i.e., it has no size), /place shapes it to its 
preferred size. It is then position^ either relative to its superframe or to a 
default location based on the gravity setting. In ClassBaseFrame and its superc- 
lasses /place defaults to /reshapefromuser. 

The gravity setting is used to calculate default positions for frames. For OPEN 
LCXDK frames the gravity setting also determines where /place will start tiling 
frames. Frame gravity is set by sending /setgravity to a specific frame class. 

The choices for gravity setting are dependent upon the particular frame class: 
normal OPEN LOOK frames expect names like /UpperLeft, /UpperRight, etc. 
Icons expect names like /Top, /Bottom, etc. For OpenLookBaseFrames gravity 
defaults to /UpperLeft. /seticongravity is support^ for backwards compatibil- 
ity. It just calls /setgravity on the base frame's icon. 

Methods: 

/place 

/setgravity 



Subframe Functions 

OpenLookFrame overrides the /open method so when a superframe is opened 
or closed all its subframes are also opened or closed. The /toptop and /tobot- 
tom methods are also overridden so subframes are sent to the top or bottom 
with their superframe. 
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Methods: 

/open 

/opensubframes 

/closesubframes 

/totop 

/tobottom 



Shared Frame Menus 

OpenLookFrame creates menus that are shared by all frames. There is one 
menu that is shared between base and icon frames, and another that is shared 
between property and command frames. If a client needs to modify the menu 
for a particular frame, the code that creates the frame menu should be copied 
and modified. This code can be found in OLframe.ps. Once modified the new 
menu should be stored with /setmenu. 

Instantiating Frames 

The frame subclasses whose names begin with "Op>enLook" are the subclasses 
that you should instantiate. Each frame fype subclass implements behavior that 
is particular to that type of frame. For example, OpenLookBaseFrame automati- 
cally creates an icon frame as a subframe when a base frame is created. 

Another example is the override of the /open method in class Open- 
LookHelpFrame. It calls the /pin method whenever a help frame is opened, 
since all OPEN LOOK help frames are supposed to be pinned when they are 
opened. 

Subclassing Frames 

This section describes techniques for defining your own frame subclasses. 

Subclassing a Single Frame Type 

The following is sample code to subclass a single frame type: 
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/MyBaseFir^me /detaultcXauJa send t] 

classbegin 

classend def 

* 3 f*mmW‘W 

You should generally send /defaultclass to the intrinsic frame class instead of 
sulx:lassing one of the OPEN LOOK frame classes directly. If your subclass 
builds on the variables and methods in the intrinsic class rather than the Open 
Look class, it should be possible for someone to change the default look and feel 
and still use your subclass. 

Subclassing Several Frame Types 

Here's some standard code to subclass more than one frame type: 




% Class containing things that ata sharad 
% among frame types. 

/l^rama /defaultclass ClassFrama sand U 
claasbegin 

% Shared frame functionality 
/BaseFrameClass (^VBaseFrame) def 
/IconFraroeClass {l^IconFrame} def 
classend def 

% Individual frame types 

/M^BaseFrame [t^rame /defaultclass ClassBaseFrame send] [] 
classbegin 

% Functionality specific to base frames 
claasend def 

/l^IconFrame {b^rame /defaultclass Class IconFrame send] [] 

Classbegin 

% Functionality specific to icon frames 
claasend def 

V y 

Class MyFrame contains everything that is needed by more than one frame 
type. Things needed by a single frame type are defined in that type's class. 
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Each of the frame type classes has two superclasses: MyFrame, providing com- 
mon new functionality; and the default implementation of the intrinsic frame 
class, providing the default frame type's functionality. 

ClassFrame contains utility methods (for example, /BaseFrameCreate) that can 
be used by subclasses to create frames that are associated with one another. For 
example, OPEN LOOK base frames have associated icon frames, so OpenLook- 
BaseFrame calls /IconFrameCreate. There are two levels of control that sub- 
classers can use to change the way associated frames are created. First, the 
/FooFrameCreate methods can be overridden. This provides the most flexibil- 
ity, but is often more than is needed. If the only thing a subclass wants to do is 
to change the class that is instantiated, it can override the /FooFrameClass 
methods to return the proper classes. Each /FooFrameCreate method in 
ClassFrame instantiates the class returned by /FooFrameClass. This is done in 
the example above, where /BaseFrameClass and /IconFrameClass are overrid- 
den to return MyBaseFrame and MylconFrame. The default frame classes (e.g., 
OpenLookHelpFrame) are used for the other frame types. Note that the 
/FooFrameClass's are executable procedures rather than direct references to the 
classes. Deferring the evaluation of the classes avoids the problem of the classes 
not being defined yet when class MyFrame is being defined. 

Adding Frame Attributes 

Adding a new frame attribute in a subclass is simple. Here's an outline of how 
you might add a new control to the frame border. For this example, let's 
assume the attribute controls whether the frame is "zoomable", that is whether it 
can grow to the full height of the screen. If it is zoomable, the frame will have a 
"zoom box" control in its border. 

First, define the new attribute by defining a variable in the subclass. The 
boolean value of the class variable is the default value used by all instances of 
this class. This value can be overridden for a particular instance by parameters 
to the /new or /setframeattribute methods. 
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Override the /Ornaments method to include the new attribute. This method 
returns attribute names on the stack and is used to construct an array of attri- 
butes that have associated ornaments, such as controls or graphics. The orna- 
ments are created and laid out in the order they are returned by the /Orna- 
ments method. If the painting order of the new ornament is important, the 
override method should do a super send then search through the attributes on 
the stack and insert the new one in the appropriate place. If the painting order 
doesn't matter, the method can simply add the new ornament at the end of the 




The subclass must provide the following methods for the new control: 
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gasis^ 

% Create the Zoom ornament. 

/ZopnCxeate { i ^ 

% ^CypioaXly mill <k> acmething like thia: 

/Zoom t<arga> claaaj /adciclieiit aelf aend 

lllll§lllilllllliii||i|ii|llllll 

I Deatroy the Zoom ornament. 

/EoomDeatroy 

% TypiOally aomethihg like; 

/Zoom /deXetebyname aelZ aend i/deatroy excih aand) iZ 

|||||||||||||||||i|||||i|||||i|ii||||i|;| 

% x*ay out the Zoom ornament. 

/Zoomtayout i % w 

% Typically something like; 

/Zoom /gethyname self send { 

% * y width height calculationa 
/reshape $ -1 roll aend 






% Notify method for the Zoom ornament. 

/ZooB^otify { % zoom^^control *> •" 
pop 

/zoomed? aelf send not /zoom aelf send 

} def 



utility Bags 

There are many ways an application might want to layout the clients of a bag. 
The NeWS Development Environment includes three utility bags that provide 
support for laying out an arbitrary number of arbitrarily-sized bag clients in 
three different ways. The names of the subclasses are: AbsoluteBag, 
RowColumnBag and FlexBag. 
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AbsoluteBag 

The absolute in the name of this bag refers to the location of the AbsoluteBag's 
clients. AbsoluteBags position their clients at application-specified x,y coordi- 
nates and keep them there no matter what the size of the bag. Clients added to 
AbsoluteBags must have an x,y coordinate as baggage. (For more information 
on baggage see the "Insertion and Removals" section above.) 

minsize 

When the minsize message is sent to AbsoluteBag it attempts to calculate a rea- 
sonable size for itself based on the x,y coordinates of the clients and their sizes 
{not their minsizes). Basically, AbsoluteBag uses the position and size informa- 
tion of its clients to calculate the smallest l^unding box that fits all its clients. 
Thus AbsoluteBag's minsize calculation tries to ensure that all its clients are visi- 
ble. However, the minsized layout many not be "pretty." 

If a class is passed to /addclient then AbsoluteBag creates a minsized client. 

Coordinate system 

Only absolute bags support two orientations of the coordinate system- top-down 
(the default) where the origin is at the upper left comer of the bag; and the nor- 
mal NeWS bottom-up system where the origin is at the lower left corner of the 
bag. Use /settopdown to change the orientation of the origin in absolute bags; 
/settopdown takes a boolean argument, true for top-down and false for bottom- 
up. 

In the top-down system the coordinates given to the bag for each client are 
taken as the distance from the top-left comer of the bag to the top-left corner of 
the client : 
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Figure 4-3: Top Down Coordinates 




true /topdown 
(absolute bags only) 




Figure 4-4: Bottom Up Coordinates 




false /topdown 

(standard NeWS coordinates) 
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RowColumnBags 

As the name of this ClassBag subclass implies RowColumnBags are designed to 
lay out clients in a grid of rows and columns. Clients added to 
RowColumnBags do not take any baggage. The default layout for 
RowColumnBags is row major order, with one column and as many rows as 
there are clients. This layout is identical to the default layout of menus. 
RowColumnBags inherit their layout from the RowColumnLayout mixin class. 

The arrangement of RowColumnBag clients can be changed using /setlay- 
outstyle. /setlayoutstyle takes three arguments: a boolean first argument to 
determine row or column major layout (true for row major; false for column 
major), the number of rows and the number of columns. If the number of rows 
and columns are specified then those numbers of rows and columns are created. 
If one of the row/column arguments is null then the appropriate value is calcu- 
lated by dividing the number of items to be displayed by the other, known 
value. If null is specified for both arguments then the bag is layed out in the 
default style. 

Every cell in the grid of a RowColumnBag is the same size. When calculating 
its minsize RowColumnBag uses the maximum minsize of all its client's min- 
sizes. Thus if a RowColumnBag had six clients of varying minsizes, it would 
determine which of the six clients had the largest minsize and multiply the size 
by six (the number of clients) in order to calculate its own minsize. 

By default RowColumnBags do not put any space between cells of the layout 
grid or between the grid and the borders of the bag. To change the default 
spacing use /setgaps to add horizontal and/or vertical spacing between cells, 
/setgaps takes two arguments the horizontal gap (or null) and the vertical gap 
(or null). The spacing is given in points. Use /gaps to determine the amount of 
space between cells, /gaps returns two numbers, the horizontal gap and the 
vertical gap. Both values are in points. 

You can also change the size of the border by using /setborder. /setborder takes 
the number of points of white space you want between the client grid and the 
bag's inside edge. 
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Flex Bags 

A HexBag is a bag in which the positions of clients are determined by execut- 
able code they pass in during /addclient This code is executed each time the 
bag is layed out. Compass-point notation is used so that clients may be placed 
relative to a comer of another client. To aid you in relative positioning of 
clients, utilities are provided. See the section ”FlexBag Positioning Utilities” 
below. FlexBag use the NeWS bottom-up coordinate system. 

The compass-point notation refers to a client's bounding box (c is center): 



Figure 4-5: Compass Point Notation 



nw 



ne 




sw 



Adding Clients 

The order of insertion into a FlexBag is critical if the bag is being used for rela- 
tive layout. During each call to /Layout the position code is executed in the 
order in which the clients were inserted. In other words, do not make the posi- 
tion of an earlier addition depend on the position of a later one. Incorrect results 
will follow. 

FlexBag's layout code expects clients to be passed to /addclient using the fol- 
lowing form: 
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( 

/name Icompa»»"point {ejwcutflbleJ client] /acWclient eflexbeg send 





The executable must return x,y coordinates that determine where the given 
compass-point of the given client is placed in the bag. The client can be either a 
class (if it is a canvas) or an instance. For example: 




puts the bottom left corner of mybutton at position 200 300 in myflexbag. Simi- 
larly: 




would create an instance of OpenLookButton with the label Buttonl and no call- 
back, make it a client of myflexbag, and place the bottom left comer of the but- 
ton at position 200 300 in myflexbag. 

FlexBag also recognizes the compass-point notation in reference to itself. When 
positioning clients relative to the bag's coordinates the FlexBag code recognizes 
the following executable form: 
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Thus: 



/q {/q fosmw 10 10 xawp) 



places the client so that its center will be offset 10,10 from the center of the bag. 
See the section "FlexBag Position Utilities" below for an explanation of POSI- 
TION and XYADD. 

Clients can be added to flex bags with no layout information. In this case you 
should set the bag's default layout specification by using /setlayoutspec. /set- 
layoutspec takes the same arguments as you use when adding clients, a 
compass-point (or null) and an executable that returns a position. 

minsize 

RexBags calculate their minsize based on the positioning information given to 
the bag when clients are added. You should note that while FlexBag don't 
presume that any shhpe or size client is being put in them the FlexBag code 
attempts to make an "intelligent" guess as to what its minsize should be by 
using a heuristic. For complicated relational positioning of FlexBag clients the 
heuristic may yield an arrangement of the clients that you find unacceptable. If 
that should occur use the ClassCanvas method /lockminsize to override 
HexBag's calculation. 

FlexBag Positioning Utilities 

FlexBags provide five positioning utilities. They are /POSITION, /WIDTH, 
/HEIGHT, /XYADD, and /XYSUB. These utilities are especially useful for 
positioning clients relative either to other clients or to the flex bag itself. POSI- 
TION, WIDTH, and HEIGHT take either a canvas instance, the name of a client 
or "Previous" or "Current" which refer to the previous and current clients, 
respectively. 

/POSITION takes a compass-point and a client's name, a canvas, or a bag and 
returns the x,y position of the compass-point of that canvas. For example, to 
position a client so that it is always in the center of the bag an application could 
do: 
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I/c {/c self POSITION} . . .] 

1 1 I 

client bag bag 

center center 

This code fragment makes the client's center and the bag's center coincide. 

/WIDTH takes a client name, a bag, or a canvas and returns its width in points. 

/HEIGHT takes a client name, a bag, or a canvas and returns its height in 
points. 

An application could use /WIDTH and /HEIGHT together to position a client 
relative to the size of the bag: 

^^[/c (self WIDTH .25 mul gelf HEIGHT .5 muX) , . 




This example positions the center of a client 1/4 of the flex bag's wfdth and at 
1/2 the bag's height. Since these are relative positions they are preserved 
independently of the bag's size. 

/XYADD does 2-D vector addition on two sets of x,y coordinates. The syntax 
is: xl yl x2 y2 XYADD xl+x2 yl +y2. 

/XYSUB does 2-D vector subtraction on two sets of x,y coordinates. The syntax 
is: xl yl x2 y2 XYSUB x2-xl y2 -yl. 



Example of Bag Usage and Subclassing 

The following example code shows how an application programmer might typi- 
cally subclass ClassBag, and use the result as the client of an OPEN LOOK 
frame (or any bag for that matter). 
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in 

% The task of a Sin^leAppBag la to provi<Je the layout policy for a Jsaalc 
% OpehXook appUcatlcai. The inaide of the windoie in auoh an ai^Xlcatlon 
% la occupied by two axeas ^ a control area of fixed heights axx} a 
% atretchable canvaa that la the main focua of Interraction. A 
% SiiqpleAppBag inanagea theae t^ro canvaaea. 

% The control area aita above the atxet<diable canvaa# and botb muat 
% adjuat their widtha to fill the frame interior ehen the iaaer reahapea 
% the frame. 

/SimpXe^pBag ClaaaBag U 
clasabegin 

% ihia bag alwaya haa exactly two cllenta. It expecta them 
% to be preaented aa argumenta to /new, and hence conauroea them 
% during /newinit. Thia bag takea the reaponaibility of giving 
% namea to clienta: /Fixed for the ^^^per area^ and /Floating 
% for the lower atxetchable region. NO baggage ia required for 
% clienta of a SlmpleRppBag. 

/newinit { % flxed-^cllent floating-client •"> *" 

/newinit auper aend 

/Floating exch /addclient self send 

/Fixed exch /addclient aelf aend 

% 7te aet the height of the /Fixed client once to ita 
% ideal aixe# and never alter in again^ Arguably# we 
% ahouldn't meaa with it at all and juat truat the 
% application to hand in a canvaa with the deaired heights 
% Thia approach faila though the application pasaea in a 
% claaa rather than an inatance. 

% The and width argumenta to /reahape are juat 
% placeholders they axe overridden in 
% /Layout. 

0 0 /minaize self send /reshape aelf send 
} /Fixed /aendclient aelf aend 

% Here^a where we decide how small we allow Use user to make 
% this bag and Its clients, dince we azen^t Overriding 
% /preferredaixe aa well. Its /preferraedaiae will default to 
% ita /minaiae. In the calculation below# we say that the min width 
% la the maximum of the min widtha for each of the clienta# and the 
% min height ia the aum of the min hei^ta of the cllwta. Thia is 
% the obvious choice given the layout of the bag. 

J 

(continued on next page ) 
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% Subtle point: m override /MinSire rather than /adnaire 
% just in case one of our clients is a graphic xrather than a 
% canvas as es^pected^ Vlhen graphics calculate their mininure size 
% they make use of the current canvas » Overriding /HinSize allows 
i us to assume that the bag *is* the current canvas. 

/MinSize < % - -> w h 

/minsize /E^ixed /sendclient self aend 
/minsize /Floating /sendclient self send 
3 '-'I roll add 3 I roll max exich 

) de£ 



% Ml hi 

% wl hi w2 h2 
% max(wX,w2) hl+h2 



This procedure is called automatically just before painting 
the bag *if* something has changed in the bag^S geometxy since 
the last time it was called. See 2*ayout and Invalidation' 

Here we reshape the two clients to fill the space available 
in the bag (as returned by /size self send) , The /Fixed client 
may be stretched horizontallyr bnt its height will not change^ 
The floating client will be streched In both dimensions to 
take up the rest Of the space. 



% 

% 

% 

% 

% 

% 

% 

% 

% 

/layout { % — ^> - 

/size /Fixed /sendclient self send eXch pqp 
/size self swd 
Z index sub 

Q 1 index 3 index ^ roll 
/reshape /Fixed /sendclient self send 



% h-Fl 
% h-Fl w h 
% h-Pi w h' 

% w h' 0 w h-Fi 
% w h' 



) def 



0 0 4 2 roll /reshape /Floating /sendclient self send 



% This type of bag doesn^t want to stroke its border Or fill itself 
% so we give it a null paint proc. 

/PaintOonvas nullproc def 
classend def 

% Below we show hpw a Bin^leAppBag mi^t be used In an application^ 

% We make the /Fixed client a FlexBag with a couple of controls in it, 

% and the /Floating client a brightly colored canvas^ 

i||||i|||li|i|ililllll|iii|||||||||||| 

/ColorCanvas ClassC^anvas [3 
ciassbegin 

/setrgb ( % rvalue gvalue bvalue -> - 

/FillColor 4 1 roll rgbcolor def 



(continued on next page) 
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/paint self send 

) def 

/mlnsise i % > winw mlnh 

50 50 

J def 
cXassend def 

/ControiAtea FlexBag [) 
classbegltt 

/PaintCanvaa nullprpc def ^ Nq paint is fine here 

% eet evety client to its preferred sise, idien it is added 
% to the bag. Ihis obviates the need for tedious reshaping 
% code outside the bag. /BegisterBag is a svieet spot for getting 
% at every instance inserted in the bag. 

/RegisterClient { % najne client - 

0 0 /pxeferredsize 3 indeac send /reshape 5 index send 
/RegisterClient super send 

) def 

classend def 

% Hake the stretchable color canvas 
/cc framebuffer /new ColorCanvas send def 

% Hake three buttons to put in the flexbag 
/bb <Black) {0 0 0 /setrgb /sendtarget $ roll send) 
framebuffer /new OpenLookButton send def 

/ifd) (White) {111 /setrgb /sendtarget 5 -1 roll send) 
framebuffer /n&rr OpenLookButton s^id def 

/xb (Random) (random random random /setrgb /sendtarget 6 roll send) 
framebuffer /new OpenLookButton send def 

% Make the color canvas the target of all buttons, 
cc /settarget l3b send 
cc /settarget id? send 
cc /settarget rb send 

% Hake the flexbag and add the buttons to it, and add a little 
% white space around the buttons. 

/fb framebuffer /new ControlAcea send def 

null {/nw {/nw self POSITION 10 -10 XYAK)) bb) /addclient fb send 
null {/nw {/sw Previous POSITION 10 sub) wb] /addcliwt fb send 

J 

(continued on next page ) 
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nuU [/ne {/ne self POSmcw ao 10 »rS05) tt] /^ddclimt fb 8end 
10 10 /fldtpadding £b 

% Create ^ txam containing a Simplaftpp3ag which in turn contains 
% the flexbag and the color canvas. 

/win [£b cc SimpXeApp&ag] t/E^ter false] 

franebuffer /new OpenlookBaseFrame send def 
(Oag Subclassing) /setlabel win send 

/place yrin send 
/activate win send 
/map win send 

newprocessgroup 
CUrxmtfile Closefile 

L ) 



Focus Management 

ClassBag provides mechanisms for "focus forwarding" and "focus noticing". 
When a bag receives the input focus, it may forward the focus to another canvas 
that is an immediate child or a more remote descendant. A bag may be 
interested in noticing when the focus is given to one of its descendants directly. 
These concepts are best explained with an example. 

Suppose you have an OPEN LOOK frame (whose class is a subclass of 
ClassBag) containing a control area (a bag) containing a text control. You want 
the user to be able to click the mouse on the frame and then to be able to type 
to the text control. Clicking on the frame will give it the input focus. However, 
it is not the frame that is interested in key strokes, but rather the text control, so 
the frame must forward the focus to the text control. The frame title area 
highlights when the input focus is anywhere inside the frame. This means the 
frame must notice the change of focus, even if the user clicks the mouse directly 
on the text control so it gets the focus without any intervention from the frame. 
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Note: the above example assumes the click-to-type focus style is being used. 
Focus forwarding and noticing also works with the follow mouse focus style. 

The mechanism built into QassBag and used by ClassFrame allow behavior 
such as that described above to be implemented very simply. How this is done 
is described below. 

Focus Definitions 

Focus Client 

A canvas interested in receiving the input focus, either for the purpose of 
procesing keys itself or for passing the focus on to another canvas that will con- 
sume keys. A canvas is designate a focus client via the utility functions 
addfocusclient and removefocusclient. 

Key Consumer 

A canvas that processes keyboard input. Set by the /setkeyconsumer method in 
ClassCanvas. A key consumer must also express appropriate interests in keys. 

Focus Forwarder 

A bag that upon receiving the input focus passes the focus on to another canvas. 
The automatic mechanism for doing this is controlled by the /FocusForwarder? 
class variable in QassBag. Focus forwarding is generally an attribute of an 
entire class, but may be enabled for specific instances by promoting /FocusFor- 
warder?. 

Focus Target 

For a focus forwarder bag, the canvas to which the input focus will be for- 
warded by the automatic forwarding mechanism. The focus target is main- 
tained automatically, but may be set explicitly with the /setfocustarget method 
in QassBag. 

Focus Noticer 

A bag that is interested in being notified when the input focus enters or leaves 
itself or any of its descendant canvases. Controlled by the class variable 
/FocusNoticer? in QassBag. 
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Focus Forwarding 

All key consumers are generally focus clients, but not all focus clients are key 
consumers. A focus client that is not a key consumer is usually a focus for- 
warder, transferring the input focus to a descendant canvas that is a key consu- 
mer. 

ClassBag provides a mechanism for autonutically handling focus forwarding. 

In the simplest case, a class that is a subclass of bag simply sets the /FocusFor- 
warder? class variable to true. This causes an appropriate interest to be created 
by /Makeinterests so the bag will be able to receive the input focus. It also 
causes FocusTarget to be initialized and maintained for the bag. When the 
input focus is given to the bag, it is automatically transfered to the focus target. 
More elaborate behavior can be achieved by overriding methods in a subclass of 
ClassBag. 

Qass Variable: 

/FocusForwarder? 

The variable /FocusForwarder? is defined as false in ClassBag and true in 
OpenLookFrame. A subclass of ClassBag that is not a subclass of OpenLook- 
Frame must redefine this variable to be true to enable focus forwarding. 

Focus Noticing 

ClassBag provides a simple mechanism for noticing when the input focus enters 
or leaves the bag or any of its descendant canvases. In the simplest case, a sub- 
class sets the /FocusNoticer? class variable to true. This causes an appropriate 
interest to be created by /Makeinterests. The subclass then overrides the /Noti- 
ceFocusEnterExit method to take whatever action is necessary, such as provid- 
ing some sort of highlighting. 

Qass Variable: 

/FocusNoticer? 
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Method: 

/NoticeFocusEnterExit 

The variable /FocusNoticer? is defined as false in ClassBag and true in Open- 
LookFrame. A subclass of ClassBag that is not a subclass of OpenLookFrame 
must redefine this variable to be true to enable focus noticing. 

How Focus Forwarding and Noticing Works 

What follows is a detailed description of the mechanisms involved in focus for- 
warding and noticing. This is useful for subclassers who want to change some 
aspect of this behavior. 

When a focus forwarder bag or any of its descendant canvases gets the input 
focus, the /NoticeFocus method is called. This method calls /NoticeSelfFocus if 
the focus is for the bag itself or /NoticeDescendantFocus if the focus is for a 
descendant canvas. /NoticeSelfFocus checks to see if there is a focus target (i.e. 
if FocusTarget is not null), and if so transfers the focus to that canvas via the 
/TransferFocus method. /NoticeDescendantFocus sets FocusTarget to the can- 
vas receiving the focus. This makes sure FocusTarget is set to the most recent 
focus recipient, even when focus forwarding does not take place, e.g. when the 
focus goes from outside the bag directly to a key consumer canvas or when the 
focus goes from one key consumer canvas to another within the same bag. 

Methods: 

/NoticeFocus 

/NoticeSelfFocus 

/NoticeDescendantFocus 

/TransferFocus 

When a new value for FocusTarget is needed, the /MakeFocusTarget method is 
called. For example, it is called when adding a key consumer canvas to a bag 
that has no focus target, or when removing a key consumer canvas that is the 
focus target. A subclasser can override /MakeFocusTarget to implement algo- 
rithms for determining which canvas should be the focus target. By default, the 
first key consumer canvas added to a bag becomes the initial focus target, and 
FocusTarget is set to null if the current focus target is removed. 
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Methods: 

/MakeFocusTarget 

When a key consumer canvas is added to a bag, the /addkeyconsumer method 
is called for the bag. This method calls /addfocusdescendant for itself and all of 
the bags from its parent to the framebuffer. The /addfocusdescendant method 
sets the focus target if it is not already set. The /addfocusdescendant message 
is sent to all bags up the canvas hierarchy so they can all have the opportunity 
to set their focus targets. An analogous procedure takes place when a key con- 
sumer canvas is removed from a bag. The /removekeyconsumer method is 
called and it calls /removefocusdescendant up the canvas hierarchy. The 
/removefocusdescendant method calls /MakeFocusTarget to get a new focus 
target if the canvas being removed is the current focus target for the bag. The 
/addkeyconsumer and /removekeyconsumer methods are also called when a 
change is made to whether a canvas is a key consumer. 

Methods: 

/addkeyconsumer 
/removekeycoiuumer 
/addfocusdescendant 
/removefocusdescendant 
/setkeyconsumer (ClassCanvas) 

Subclassers way want to develop algorithms for setting a bag's focus target 
based on the last times canvases had the input focus. For example, a QassBag 
subclass might override /MakeFocusTarget so that when the current focus tar- 
get canvas is removed from a bag other key consumer canvases in the bag are 
checked and the one that had the focus most recently becomes the new focus 
target. ClassCanvas provides the /setlastfocustime and /lastfocustime methods 
as a standard way of storing and retrieving the last time a canvas had the input 
focus. Key consumer canvases should call /setlastfocustime when they receive 
the input focus. This will allow them to be placed in bags that use last focus 
time. 
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Methods: 

/lastfocustime (ClassCanvas) 
/setlastfocustime (ClassCanvas) 



Methods: 

/setfocustaiget 

/focus target 

/setkeyconsumer 

/removefocusdescendant 

/removekeyconsumer 

/addfocusdescendant 

/addkeyconsumer 

Aastfocustime 

/MakeFocusTarget 

/NoticeDescendantFocus 

/NoticeFocus 

/NoticeFocusEnterExit 

/NoticeSelfFocus 



Class Variables: 
/FocusForwarder? 
/FocusNoticer? 
/FocusTarget 
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ClassSelectionList is the basis for menus and setting controls (Exclusive, NonEx- 
clusive and Choggles). It is not designed to be instantiated directly. The idea 
behind a selection list is that a single canvas manages a grid of regularly spaced 
items that can be independently selected via the mouse. The most common use 
of selection lists is for menus. 



Menus 

This section covers the more important details of the programmer's interface for 
OPEN LOOK menus. For information on using OPEN LOOK menus please 
consult the OPEN LOOK UI Style Guide. 

This section concentrates on the OpenLookMenu class. This section covers those 
methods deemed most important for using menus. The complete set of 
methods associated with OpenLookMenu and its superclasses can be found in 
section 2. 

Introduction 

ClassMenu is an intrinsic class implementing menus; it supports hierarchical 
pop-up pinnable menus. ClassMenu, as with other intrinsic classes, is meant to 
be subclassed rather than instantiated; it provides the foundation for OpenLook- 
Menu. You can subclass QassMenu if you want functionality that is substan- 
tially different from that which OPEN LOOK menus provides. And while 
OpenLookMenu is generally intended for instantiation, it can be subclassed to 
implement small changes in the class, such as having all menus come up using a 
font that differs from the default. 

Applications can automatically associate a menu with another canvas. The 
News Development Environment takes special care to nwnage the relationship 
between canvases and their associated menus. By default, an instance of 
ClassCanvas does not have a menu but QassCanvas has been designed to 
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expect a menu. The NeWS Development Environment provides procedures to 
facilitate this relationship through the ClassCanvas method /setmenu. For an 
explanation of /setmenu see "Callbacks, Targets and /setmenu" in this chapter. 

Creating Menus 

Menus consist of arrays of items. OpenLookMenus can have four types of 
items: command, submenu, exclusive, and nonexclusive. The visual look, type 
and callback of menu items are specified by a set of triples specified at the time 
of menu creation. That is, the triples, one for each item, can be given as argu- 
ments to the new method when a menu is instantiated. 

The most common way to describe an item is: 

[thing I graphic null] submenu Igenproc proc|null] 

visual type callback 

field field field 

This way of specifying items can be used to create menus with an arbitrarily 
large number of items. Item typ>es can be mixed using the above model. For 
example the following code would specify three types of items in one menu: 



% Xtm 

% Exqlu^iw item 
% Sulbrnenia 
comnand item 
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A less general way of specifying a triple can be used: 

[thing I graphic . . .] null 1 submenu | genproc proc | null 

visual type callback 

field field field 

This way of specifying menus is used to create menus where all the items will 
be of the same type and have the same callback. 

Visual Look Field 

You can specify the visual look field of the triple using either a graphic or a 
thing, both described in ClassGraphic. Whatever graphic is used for the visual 
field, by default, will be inserted in an instance of OpenLookMenuButton- 
Graphic. 

A thing is a PostScript data structure, either a string or an array. The array con- 
tains the string as well as optional attributes used to display the string. Two 
common attributes used are a font to render the string in and a color to render 
the font in. 

Type Field 

The type field is used to indicate the type of the menu. The type field is one of: 

■ null to specify a command menu item 

■ a submenu (sublist) or a procedure to create a submenu (genproc) 

■ an array containing the name /Exclusive to specify an exclusive item 

■ an array containing the name /Nonexclusive to sp>ecify a nonexclusive 
item 

Callback Field 

The callback field is null when the item is of type submenu. If the item is not of 
type submenu then the callback field specifies the action to be taken when the 
item is selected. If non-null the callback field must be an executable PostScript 
array that consumes the menu from the stack. 
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Limitations 

The News Development Environment's OPEN LOOK menus do have some lim- 
itations and as such, do not currently allow for some OPEN LOOK U1 func- 
tionality. Menus containing both exclusive and nonexclusive choices are not 
supported well. For example: a menu is created that has two command items, 
three exclusive items and one nonexclusive item. One might expect that for the 
purposes of menu maiupulation the menu had four items: the two command 
items, the non exclusive item and the three exclusive items grouped as a single 
item. In fact in the NeWS Development Environment, menus cannot handle this 
grouping of items. 

This lack of grouping ability means that a menu cannot contain two sets of 
exclusive items that operate independently. Turning on any exclusive item in a 
menu will turn off all others. 

Laying Out Menus 

The default menu layout is one column and the number of rows equal to the 
number of items. However, you can lay out menus with multiple rows and 
columns. Moreover, you can specify whether the menu will be layed out in row 
major or column major order. 

To set the layout of a menu instance to be other then the default use /setlay- 
outstyle. /setlayoutstyle takes a RowMajor? boolean first argument; true lays 
out the menu as row major and false lays out the menu as column major. The 
next two arguments specify the number of rows and the number of columns 
respectively; either or both may be null. 

If you specify the number of rows and/or columns, then those number of rows 
and/or columns are created. If you specify null for one of the arguments then 
the appropriate value is calculated automatically by dividing the number of 
items to be displayed by the other, known value. If null is specified for both 
rows and columns the menu is layed out in the default style. 

If you specify a matrix that is too large for the number of items there will be 
empty spots in the matrix. If too many items are specified for the size of the 
matrix the excess items will not be shown. 

You can query the layout specifications of a menu using /layoutstyle. The 
RowMajor? boolean, the number of rows, and the number of columns are 
returned. 
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Manipulating Menus 

Once you have created a menu several methods are available to change features 
or query current menu settings. Some of the more conrmnonly used methods 
allow a program to insert, delete, disable and determine the last item selected 
on the menu. 

You can access menu items using their index. The terms location and index are 
used interchangeably. 

Use /insert to put a new item into an existing menu at a specified location, 
/insert takes an index and an item triple as arguments and preserves the menu's 
default. Similarly, /delete removes an item at the specified location while 
preserving the menu's default selection. Any field of an item's triple can be 
changed using /change. If all the fields aren't being changed then null is used 
as placeholder when the triple is passed into /change. 

Enabling and disabling an item refers to two things: the visual state of the item 
and the ability of the item to get the combination of mouse drags and button 
ups. An item that is enabled will be highlighted on a mouse drag and execute 
its callback on the button up. An item that is disabled will get neither the 
mouse drag or the button up. A disabled item is "grayed out” to distinguish it 
from an item that is enabled. 

Use /enableitem to enable a menu item and /disableitem to disable an item. 

The /itemenabled? method allows you to query an item to determine if it is 
enabled or disabled. 

Menu Values 

The value of a menu is the index of the last item selected. Send /value to a 
menu instance to determine its current value. 

Use /setvalue to change the value of a menu. If an item is an exclusive item and 
it is turned on when /setvalue is called on it, the item is not turned off. Use 
/nonxvalue to determine which nonexclusive menu items are turned on. It 
returns an array of the indices of all the nonexclusive items currently set. If no 
nonexclusive values are set an empty array is returned. Use /xvalue to deter- 
mine which exclusive value is currently set. It returns the index of the item, 
/setvalue does not execute an item's callback. Applications that want an item's 
callback executed immediately after the item is set should call /doaction. 
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Pinned Menus 

It is worthwhile noting that there are no programmer interfaces to allow access 
to the pinned version of the menu. The pinned version is a copy of the menu. 
Code in class OpenLookMenu will perform the necessary actions to keep the 
pinned copy up-to-date with changes made to the menu. 

To give menus a pin (or to remove it) use /setpinnable. Use /pinnable? to 
query a menu to determine if it is pinnable. 

Callbacks, Targets and /setmenu 

After a menu is built several conditions must be met before the "right" thing can 
happen when a menu item is selected. First a menu and a canvas must be asso- 
ciated so that MENU down produces the correct menu. Second, when a MENU 
up occurs the correct callback is executed. Finally when the callback is exe- 
cuted the correct object is affected. The NeWS Development Environment pro- 
vides several methods and a mixin class to help you manage the relationship 
between menus and other canvases. 

You can use the QassCanvas method /setmenu to associate a menu with 
another canvas, /setmenu takes a menu as its argument and is sent to a canvas. 

Using /setmenu causes the canvas to express an interest in the MENU button 
down and to display the menu when one is noticed. When /setmenu is used 
menu callbacks will execute in a process forked from the canvas's event 
manager process. Having the callback execute in the canvas's event manager 
process group guarantees that the same userdict and stdout (for sending tag- 
prints), exists when the callback is executed as when the canvas was activated. 

However, before the correct callback can be executed a program must determine 
which item was selected. Determining which item was selected is easy because 
when an item is selected the menu is pushed on the stack. 

With the menu on the stack programs can call /value to determine which menu 
item was selected, /value returns the index of the last item selected. Thus in 
the simplest case to determine which item was selected a callback would con- 
tain: 
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With the item selected identified the correct callback can be executed. Then the 
callback needs to send its methods to the correct object. 

The News Development Environment provides targets to help programs send 
callback methods to the correct object. If /setmenu was used to associate the 
menu with a canvas then the QassTarget method, /sendtarget can be used to 
send the callback methods to the canvas, /sendtarget is sent to the menu. Thus 
in the simplest case the callback would contain: 

I /nyubthod /MnidHitxisret 3 -1 xoU <«nd 




/setmenu associates a menu with another canvas; it doesn't set the target. 
Instead, by default canvases set the target of their menus to be themselves when 
the menu is brought up over them (see Chapter 3, Canvases). 

Using Targets Manually 

While most applications will want the Toolkit to manage menus, functionality is 
provided to allow applications to handle menus manu^ly. If you require 
manual handling of menu display, e.g., having different menus pop-up in dif- 
ferent areas of the same canvas, should not use /setmenu. 

Such applications could, for example, express interest in MENU mouse down, 
calculate where in the canvas the mouse was when the mouse down was 
received, then make an explicit call to /showat to display the correct menu for 
that region of the canvas. 

Targets can be set explicitly using /settarget In addition, applications that don't 
want the canvas over which a menu is brought up to be the target of the menu 
can change the default behavior by using the ClassCanvas method /autotarget- 
menu: 
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See Chapter 8 for a complete discussion on using targets. 

Shared Menus 

Since canvases are the default target of the menus brought up over them, appli- 
cations can easily share the same menu between different instances of a canvas. 
There are two cases: 

1 . All instances of a class share the same menu. Use /CanvasMenu a 
ClassCanvas class variable: 




2. Share a common menu between instances of different classes. Then an 
application would use /setmenu and send the menu to each canvas 
instance. 

Settings 

OpenLookXSetting 

This class implements the Open Look exclusive setting control. Since this class 
is derived from QassSelectionList, entire group of settings uses a single canvas, 
has a single event manager. 

Although not derived from QassControl, exclusive settings behave much like 
controls. They have a single value and a client-supplied notify proc. They may 
be placed into bags along with controls. However, a difference is that although 
individual items may be disabled, there is no /disable method that applies to 
the entire setting group. 
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Exclusive settings are created from a list of items. The list is similar to the one 
used to create menus, except there is nothing corresponding to a submenu. 
There are two forms of parameter to /new: 



[thing] graphic procjnull qanva? 
[thing Igraiphic procihuU canvas 



The first form is ai\ array of graphic/proc pairs. Each graphic may be either an 
instance of a graphic class, or may be a "thing" suitable to create an instance of 
class OpenLook)^ttingGraphic. The proc is a notify proc like that of any 
menu or control. It is called with the exclusive setting on the operand stack. 
The second form uses a single proc for all items and is used when the same 
notify proc is used for all setting items. 

As with menus, the items in a setting are ordered. The value of the setting con- 
trol is an integer corresponding to the selected item. The first item is numbered 
0. The Class^lectionList methods for managing lists can be used to insert, 
delete and change items. Individual items can be enabled and disabled. 

Methods: (all in ClassSelectionList) 

/insert 

/delete 

/change 

/enableitem 

/disable! tern 

/itemenabled 

OpenLookXSetting uses a row /column layout algorithm to arrange its choices 
(it has class RowColumnLayout as a superclass as well as ClassSelectionList). 
The /setlayoutstyle method is used to control whether the exclusive choices are 
arranged in a row, a column or a matrix. 
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Methods: (all in class RowColumnLayout) 

/setlayoutstyle 

/layoutstyle 

/cellcount 



Example 

This code builds a demo frame that contains a bag that contains a simple 
exclusive setting. When an item is selected, the frame's footer displays the new 
setting. 







A 


/frama /demo OpeALdokBaseFrame send def 
% Create the bag and put It In the 
/bag tramebuft^ /new BowColwinBag send def 
bag /setcllent frame send pop 
% Create the exclusive setting, 

1 (3D0> (1200) (2400) (4800) 

(9600) (19200) (57600)1 


% Setting cboioes 




/vaXuething 1 Index send null 
/setfooter /sendtarget 5 -1 roll send 

framebuffer 

/new <)penLoo3cXSettlng send 
/xsetting exch def 


% setting string null 

% Setting notify proc 
% Parent canvas 




% Set the setting' s target to be the frame, 
frame /settarget xsettlng send 






% Sh«$>e the setting to Its mlnhnum sire* 

0 0 /mlnslze xsettlng send /reshape xsettlng send 




% Put the setting Inside the bag. 
/xsettlng xsettlng /adciclient bag send 






% Make sure the setting is displayed, 
/paint bag send 

V 




/ 
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Notes: 

The creation of the frame and bag are kept very simple for this example. A 
RowColumnBag is used so we don't have to provide any information about the 
position of the setting. 

It is not necessary to /activate the setting when it is put inside a bag - the bag 
does this automatically. 

The /settarget method is used to make the setting's target be the frame. The 
setting's notify proc uses /sendtarget to call the /setfooter method in the frame. 
The /sendtarget method is sent to the setting, which is on the operand stack 
when the notify proc is called. 

The /value thing method returns the "thing” corresponding to the current value 
of the setting control. This will be one of the strings (300), (1200), etc. 

The bag is explicitly painted at the very end of the example because the frame 
and bag were already activated earlier in the example. (The frame is activated 
by the /demo method.) In many actual cases the bag will be populated with 
controls before its frame is activated. When the frame is activated the bag and 
its controls will be painted automatically, eliminating the need for an explicit 
call to /paint. 

The default layout style is to place the setting items in a single column. This 
may be changed with the /setlayoutstyle method. For example, the following 
will change the above setting control from vertical to horizontal: 



% Make layout )>e ty rows* with one row and as many columns 
% as needed. 

true 1 null /setlayoutstyle xsettlng send 
% Reshape the setting control. 

0 0 /minsize xsetting send /reshape xsettlng send 



% Invalidate and reqpaint the bag. Invalidation causes the bag 
% to relayout its contents. This is necessary because of the new 
% shape of the setting control. 

/invalidate bag send 
/paint bag send 
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OpenLookChoggle 

An OjjenLookChoggle is a variation on the OpenLookXSetting in which it is 
possible for no item to be selected. If the user clicks the mouse on the selected 
item, it is deselected and no other item is selected. The /value rx^thod will 
return null for the control when no item is selected. Other than this difference, 
OpenLookChoggles are exactly the same as OpenLookXSettings. The name 
"choggle" is a blend of "choice" and "toggle" and was once used in the Open 
Look specification to as the name for what is now called simply a "variation on 
exclusive settings". 



OpenLookNonXSetting 

A nonexclusive setting is a group of choice items, any number of which may be 
selected at the same time. Clicking on an item toggles its selected state. This is 
a multiple valued control — its value is an array of values corresponding to the 
selected items. The /setvalue method takes either a single value of an array of 
values, /value returns an array of values, and /valuething returm an array of 
things. 

Methods: 

/value 

/setvalue 

/valuething 



The spacing between the setting choices is 4 by default. This may be changed 
with the /setgaps method. 

Class OpenLookNonXSetting is a subclass of OpenLookXSetting. Except for 
their having mulitple values and the spacing of their choices, nonexclusive set- 
tings are identical to exclusive settings. Their settings are specified by the same 
parameter to /new, items may be inserted, deleted or changed the same way, 
and the layout style is controlled the same way. 
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Example 

This example creates a nonexclusive setting and adds it to the bag from the pre- 
vious example. 



% Ct^td tb 0 nondxcXudl^ Aetting. 
t(dold) (Ittlia) CdPddfliAd) (Ovdrstrllce)} 

/valudthing X Sjodax aand 
0 eacqh Uppand ( ) append) fpralX 
rwXX exch 

/setfeoter /aendtarget S zioll aend 
framebuffer 

/bew OpebLobkMonXSetting send 
/nxsetting each def 



II Setting uheioea 



aettlng atringarray 
aettlng atrlng 
aetting null string 

Setting notify proc 
Parent canvas 



% Set the setting's target to the frame* 
frame /aettarget nrsetting send 

% Shape the setting to Its minimum size* 

0 0 /minsize nxsetting send /reshape nxsetting send 

% Xay out the hag in rows^ so the nonexcXusive setting wiXX 
% be to the right of the ercXusive setting^ not beXoir it. 
true nulX S /setlayoutstyXe bag send 

% Add the setting to the bag. 

/NonXSetting nxsetting /addcXlent bag send 



% Hake sure the setting is displayed, 
/paint bag send 



Notes: 

This example assumes the exclusive setting from the previous example is still 
laid out as a column. If it is a row, the example still works, but doesn't look as 
good. 

The /valuething method returns an array of things for the nonexclusive setting. 
Each thing is a string such as (Bold) or (Italic). A single string is built by 
appending together all the strings in the array. The resulting string is used to 
change the right part of the frame's footer. 
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The layout style for the bag is set in this example because a second client is 
being added to the bag and therefore it matters whether the bag layout is in a 
row or a column. 



Here are some examples of setting and retrieving the value of the nonexclusive 
setting. 
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ClassControl 

Controls are canvases with the following features: 

■ a value 

■ a notify (callback) procedure 

■ a state of enabled or disabled 

■ a tracking process that is created for user interaction 



Value 

A control has a "value" that may be changed via a user interaction or program- 
matically. The general mechanism provided by ClassControl allows a control's 
value to be any object. Subclasses will generally define some domain of legal 
values for the controls they define. For example, a check box might allow only 
the values true and false, a dial might allow integers from 0 to 10, and a text 
field might allow any character string. Each subclass defines what happens if an 
attempt is made to set the value to something not in the domain of legal values. 
A subclass might allow multiple values, in which case the control value might 
actually be an array of the current values. 

A subclass of ClassControl must provide a /PaintValue method. This method is 
called whenever the control's value changes. The method may either paint the 
control according to the new value, or may compare the new value to the old 
and do an incremental paint. 
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Methods: 

/value 

/setvalue 

/PaintValue 



Notification 

If a control's value changes as the result of an interaction initiated by the user, 
the client application is informed via the "notify” procedure. This is a fragment 
of code that is supplied as an argument to /new for the control, or may be set 
with the /setnoti^^roc method. The notify proc is called with the control itself 
on the operand stack. The notify proc can query the control for its value or any 
other relevant information. The notify proc must remove the control from the 
stack. It is generally best to not rely on a particular execution context from 
within the notify proc. Here's a sample notify proc that prints the current value 
of the control: 

Iiaiiii 

/jnynotify { ^ control •> •- 
/value exch send 

console (Control value is %0 [4 -1 roll] fprlntf 

} def 

^ J 

The methods /callnotify and /checknotify cause notification to take place, i.e. 
the control is pushed onto the operand stack and the control's notify procedure 
is executed. The /callnotify method unconditionally notifies. The /checknotify 
methcxi calls /CallNotify? and uses the returned boolean value to decide if 
/callnotify should be called. Generally, you should call /checknotify, not 
/callnotify. The /CallNotify? method can be overridden by a subclasser to con- 
trol when notification takes place. The default /CallNotify? method checks to 
see if the current value of the control is different from the value at the last 
notification, and if so the notification takes place. 

Some controls are output-only and therefore do not support user interactions 
and do not do automatic notification. The only way notification can take place 
for these controls is via an explicit call to /che^notify or /callnotify. An exam- 
ple is a read-only text control. 
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All controls take a notify proc as an argument to their /new method. If the 
argument is null, no notification takes place. Since controls are canvases, they 
also take a parent canvas as an argument to new. Control subclasses will often 
define additional parameters to /new. 

Methods: 

/new 

/setnotifyproc 

/notifyproc 

/checknotify 

/callnotify 

/notifiedvalue 

/CallNotify? 



Enabled / Disabled State 

A control has an enabled /disabled state that is changed by the /enable and /dis- 
able methods. A disabled control is "read only" and does not respond to user 
input. Typically a disabled control will offer a visual indication of its state, such 
as dimming itself. 

Methods: 

/enable 

/disable 

/enabled? 

/PaintEnabledState 



Tracking 

"Tracking" refers to the temporary processing of certain events during user 
interaction with a control. It is t)^ically initiated by the user clicking the mouse 
in the control. At that time certain tracking interests are expressed, allowing 
processing of, for example, mouse button up events to terminate tracking and 
mouse enter/exit events for highlighting the control. 

Controls automatically express an interest in the down transition of PointButton 
(defined by The OPEN LOOK UI as the left mouse button, if not overridden by 
the user.) This causes the /EventHandler method to be called, which by default 
does nothing. A subclass will typically override this method to call /StartTrack- 
ing, which will call /trackon if the control is enabled. The /trackon method 
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creates a track manager process (accessable via the /trackmgr method) and 
expresses the transient tracking interests. 

There are several "standard" tracking methods that, if supplied by a control sub- 
class, will be called automatically during tracking. If /ClientDrag is supplied, it 
will be called for every mouse movement within the control. If /ClientEnter or 
/ClientExit is defined, it will be called when the mouse cursor enters or leaves 
the control. The /ClientDown and /ClientUp methods are called at the start and 
end of tracking. 

If a /ClientRepeat method is provided, a timer interest is expressed and the 
method will be called after a time interval specified by ClientStartTime. The 
/ClientRepeat method will typically take some action, such as calling /Client- 
Down, and then generate another timeout event so it will be called again: 




/ClientBep^t { % event »*> - 

ClientRepeatTlme /qanva9 9 elf 
curtentptoce99 BendtiKieoiatevent % - 

) def 

Note that the event passed as argument to /ClientRepeat will not have mean- 
ingful /XLocation and /YLocation fields. The event's /Name will be 
/TimeOutEvent rather than the name of the event that started tracking. 



Methods 


/trackon 


/ClientDrag 


/trackoff 


/ClientEnter 


/trackmgr 


/ClientExit 


/trackinterests 


/ClientRepeat 


/StartTracking 


/ClientStartTime 


/EndTracking 


/ClientRepeatTlme 


/ClientDown 


/EventHandler 


/ClientUp 


/MakeTrackInterests 


/BuildTrackInterest 
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ClassDialControl 

A dial is a control with a numerical value bounded by minimum and maximum 
values. Examples of dials are circular knobs and meters, linear scrollbars and 
thermometer-type gauges. 

User interaction with the dial may change its value either to an absolute value, 
or to a value computed by adding or subtracting a "delta" to the current value. 
Values are constrained to be within the dial's "range", i.e. between its minimum 
and maximum values. The granularity of the dial may be controlled via "nor- 
malization". For example, a dial may have a range of 0 to 100 and normalization 
may be used to contrain legal values to multiples of 10. Normalization values 
will generally be less than or equal to delta values. 

Methods: 

/setrange 

/range 

/CheckValueBounds 



Deltas 

Deltas are named increments for amounts a dial's value may change relative to 
its current value. Deltas are defined in subclasses of QassDialControl. For 
example, a scrollbar may have deltas named /Line and /Page. A delta may be a 
constant value or an executable code fragment that produces a dynamically 
computed value. 

The /setdelta method allows you to define new delta names and values for a 
control. The /incrementvalue method takes an integer and a delta name and 
changes the dial's value by the delta amount multiplied by the integer you sup- 
ply. The /motion method returns the amount and delta name of the last change 
in the dial's value. It is most useful when called from the dial's notify proc. 
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Methods: 

/setdelta 

/delta 

/motion 

/incrementvalue 

/SetMotion 



Normalization 

The normalization value, which may be either constant or dynamically com- 
puted, specifies the difference between consecutive legal values of the dial. For 
example, a dial with a minimum value of 0, a maximum value of 100 and a nor- 
malization of 2 could have only even values from 0 to 100. Delta values will 
usually be some integral mulitple of the normalization value. Normalization is 
most commonly used to contrain the values a dial may acquire from an absolute 
motion, rather than from a relative motion involving a delta. 

Methods: 

/setnormalization 

/normalization 

/Normalize 
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Class Button 



OpenLookAnchorButton 



Ope-g^kButton ^ ^_^m^kAbbrBu«o„S.ack 

OpenLookMenuPin nrw»«TYv^vYc-«4norr«f*«i nrv.nT^VFrafy>flrir»c« 



ClassTaiget 



'JT' 



ClaMConttolc 



wButton^- OpenLookMenuPin 

' OpenLookNumericButton 
1 OpenLookPin 

I ClassDialControl 
ClassTextControl 
I OpenLookNumeric 
OpenLookFraznecomexs 



OpenLookXSettingControl OpenLookFrameClose 
‘ OpenLookCheckBox 

A 

OpenLookFramePin 



A button is a very simple control, having a graphic and a boolean value. When 
the value is true, the button is highlighted. When the mouse is clicked on the 
button, tracking is started. When the mouse cursor is inside the button, the but- 
ton is highlighted. When the mouse button is released, the button's notify proc 
is called, and the button's value is set back to false, causing it to be 
unhighlighted. 

Graphic 

A button contains a graphic, which determines the button's appearance. When 
you create a button, you must supply either an existing graphic instance, or a 
"thing”, from which a graphic may be created. If you supply a terminal graphic, 
it determines the button's appearance completely. If you supply a thing or a 
non-terminal graphic, it is enclosed inside another graphic that supplies the but- 
ton border. 
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Methods: 

/new 

/setgraphic 

/graphic 

/EnGraphic 

/UnGraphic 

/CreateGraphic 



Notification and Value 

When you use a button you are generally interested in the notification that takes 
place when the button is pressed but not the button's value. The notify proc 
gets called when the mouse button is released on the button. The value of the 
button is true when it is highlighted and false otherwise; so the value will 
always be true during the notification. 

OpenLookButton 

Class OpenLookButton implements a button with OPEN LOOK appearance. As 
with all buttons, the appearance of the button is specified via a "thing" or 
graphic parameter to /new. 

Button Examples 

The simplest possible button has a trivial notify proc and has the framebuffer as 
its parent canvas: 
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||:|||||||;«^^^ 

(Po It) % Putton l40>eX 

console (Donel) fprlntf) % Kotify ptoe 

framebuffer % Parent canvas 

ynew (^>enI*ookPutton send 
/button exch def 




% Shape the button to Its minimum slase. 

100 100 /mlnslze button send /zesha)pe button, send 




% Start event processing - maJce button mouse sensitive, 
/activate button send 




% Actually paint the button, 
/paint button send 

V 


J 



Notes; 



The notify proc is called with the button itself on the operand stack. Since the 
"Done!" message does not use the button at all, the button is simply popped 
from the stack. 

The /paint method call is necessary because the button has the framebuffer as its 
parent canvas. Since the button is a transparent canvas and the framebuffer 
does not automatically ask transparent children to paint themselves, the /paint 
must be explicit. If the button had been placed ii\side a bag, the /paint would 
not be needed because bags automatically paint their child canvases. 

A slightly more involved and realistic example puts the button inside a bag 
which is inside a frame. 



Controls 



6-9 




Controls 



f ^ ^ ^ 

/frama /<3^mo ppanLookBad^rama dmd def 

% Create U» bag and put: it in the frame* 

/bag framebuffer /new BowColnmnBag send def 
bag /setqllent frame send p<^ 

(Repaint Frame) % Batten label 

{/paint /aendtarget 3 ^1 rail send) % Notify prod 
framebuffer % Parent canvas 

/new ppeiiDookButton send 
/button exch def 

% Set the button^ s target to be the frame, 
frame /settarget button send 

% Sh^ the button to its jninimum Site* 

0 0 /mlnsiae button send /reshape button send 

% Put the button inside the bag* 

/RepaintButton button /addelient bag send 

% Halce sure the button is displayed. 

/paint bag send 

V ^ y 

Notes: 

The creation of the frame and bag are kept very simple for this example. A 
RowColumnBag is used so we don't have to provide any information about the 
position of the button. 

It is not necessary to /activate the button when it is put inside a bag — ^the bag 
does this automatically. 

The /settarget method is used to make the button's target be the frame. The 
button's notify proc uses /sendtarget to call the /paint method in the frame. The 
/sendtarget method is sent to the button, which is on the operand stack when 
the notify proc is called. Another technique for repainting the frame would be 
to send /paint to the parent of the parent of the button (the button's immediate 
parent is the bag). This is somewhat messier and less flexible than using a tar- 
get. 
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OpenLookButtonStack 

An OpenLookButtonStack is an OpenLookButton that has a menu associated 
with it. A different graphic (class OpenLookButtonStackGraphic) is used so the 
button contains an arrow to indicate there is a menu. The name "stack” is an 
artifact of an earlier Open Look revision in which what is now called a "menu 
button” was called a "button stack”. 

The /new method includes a specification for the menu: either a menu object 
itself or an array that can be used to create the menu. If the parameter is an 
array, it is used to instantiate the menu, and has the following form: 

f ^ 

tthln^l graphic genprCc | subliat ) null proc inull « . . J 

V y 

Menus created in this way have the framebuffer as their parent. The /setmenu 
method allows you to change the menu associated with a button stack, and, like 
/new, it takes either a menu instance or a menu specification array as its argu- 
ment. 



Methods: 

/new 

/setmenu 



Notification 

Notification for OPEN LOOK button stacks is different than for most other con- 
trols. For most controls if you do not provide a notify proc, no notification will 
take place. However, for button stacks, if you provide no notify proc, pressing 
the button will cause the notify proc for the default item on the associated menu 
to be executed. For most cases this is the desired behavior so the notify proc 
parameter to /new for the button stack will be null. 
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Methods: 

/NotifyUser 

OPEN LOOK button stacks display the menu default in the button when the 
button is pressed. This is implemented by the /DisplayDefault and 
AJnDisplayDefault methods, which may be overridden by subclassers. 

Methods: 

/DisplayDefault 

/UnDisplayDefault 
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Button Stack Example 

% Create the framer 

/fteme /<Jepno Ppenl<x>k5aaePraine send de£ 



i Create the hag and put it in the frame ^ 
/hag framahuf fet /new RowCoinmi^ag eend def 
bag /aetclient frame sehd pop 



(Framo) 

lillllilll 


% button 


label 








(Close) 


null 


(false /open 


/sendtarget 4 -X roll 


send) 




(Zoom) 


null 


{true /zoom 


/sendtarget 4 -1 roll 


send) 




(UnzQcin) 


null 


(false /zoom 


/sendtarget 4 rplX 


send) 




(Repaint) 


null 


l/paint 


/sendtarget 3 -X roXX 


send) 




(Flash) 


null 


(/flashframe 


/sendtarget 3 roll 


send) 




(Front) 


null 


{/totop 


/sendtarget $ ^X rpll 


send) 




(Back) 


null 


i/tobottoitt 


/s^^arget 3 -X roXX 


send) 


null 


(Reshape) 


null 


I 

I 


/sendtarget 3 --I roll 


send) 








% Button nbti)^ proc 




:fra2n^;>u£far; 








4 Parent canvas 





/new OpenLookButtonStaclc send 
/buttonstack exch def 

% Set the targets for the button stack and the ntenu to be the frame* 
frame /settarget buttonstack send 

% Shape the button to its minimum sire. 

0 0 /minsiza buttonstack send /reshape buttonstack send 

% ^t the button inside the bag. 

/Buttonstack buttonstack /addclient bag send 

% Make sure the button is displayed. 

/paint bag send 

V J 

Notes: 

The button stack menu performs various operations on a frame, which is esta- 
blished as the menu's target. The menu has no submenus, so that parameter is 
null for each menu item. Some of the frame methods take arguments, which are 
included in the menu item notify procs. 
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The notify proc for the button itself is onutted, i.e. is null. When the user clicks 
on the button, the notify proc for the default menu item is called. The notify 
proc for the button itself is omitted, i.e. is null. When the user clicks on the but- 
ton, the notify proc for the default menu item is called. 

For button stacks, the target for the menu is automatically set to the target for 
the button stack. It is not necessary to explicitly set the target for the menu; 
only the button stack target is set in the example. 

OpenLookAbbrButton 

Class OpenLookAbbrButton implements a small square button with an arrow 
inside it and an optional label to its right. 

The button label may be an arbitrary graphic. The argument may be a "thing", 
in which case it is used to create an irrstance of class OpenLookLabelGraphic. If 
no graphic is desired, the parameter to /new should be null. 

The direction that the button's arrow points may be changed via the /setaixow 
method, which takes arguments /Left, /Right, /Up and /Down. The defairlt 
arrow direction is down. 

OpenLookAbbrButtonStack 

Class OpenLookAbbrButtonStack combines Op>enLookAbbrButton and Open- 
LookButtonStack to produce an an abbreviated button, a label, and a menu. 

The button's label reflects the most recent selection from the menu. When a 
menu item is chosen, the item's notify proc is called and the button stack label 
is changed to match the menu item. As with button stacks, the menu default is 
previewed in the button's label when the button is pressed. When the button is 
released, the label reverts to its previous value, and the button stack notify proc 
is called. If there is no notify proc for the button stack (the parameter to /new 
was null), the notify proc for the default menu item is called. 

The button stack's label, menu, notify proc and parent canvas are specified as 
paramters to /new. The label is specified as a "thing" or as a graphic. The 
parameter may be null, in which case no label is displayed, either initially or 
when a menu item is selected. The menu is specified the same as for class 
OpenLookButtonStack. The notify proc is the proc called when the abbreviated 
button is pressed, and may be null. Remember that each item in the associated 
menu may also have its own notify proc. 
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Example 



/f tame /damo OpenL(X>kBadd£*rakna ser^ de£ 

% Create the bag and put it in the frame, 
/bag framebuffer /new RowOoluimBag send def 
bag /aetciient frame 9 er)d pop 



% Create the menu to uae with the button ^ach; 
[ (icona) <CoXors) (Menua) (Text) (Meaaagea) 
(Mooae iSettings) (Keyboard Equivalenta) 1 
[/Exclusive) 

console (% aeieoted.Q 
I/vaiuethlng 5 roil send] fprintf 

ililiiiiiiiiiiiiiii 

framebuffer 

/new OpenXx>ok!Kenu send 

/menu exch def 



% Menu items 
% Exclusive choice menu 
% Hotify proc 



% Menu parent 



% Set menu default to “Text’* 
3 /setdefault menu send 



% Create the abbreviated button stack. 
(Text 



null 

framebuffer 

/new OpenXiOokAbbrButtonStack send 
/buttonstack exch def 



% Initial label 
% Stack menu 
% Button notify pxoc 



% Shape the button to its mininaan. sike. 

0 0 /mlnsize buttonstack send /reshape buttonstack send 

% Put the button inside the bag. 

/Buttonstack buttonstack /addcHent bag send 



% Make sure the button is displayed* 
/paint bag send 



Notes: 

The menu is created and then used as a parameter when the button stack is 
created. This is necessary in this example so the menu may contain exclusive 
choices. If "normal" menu items were wanted, it would be possible to create the 
menu implicitly with an array parameter to the /new method of OpenLookAb- 
brButtonStack. 
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The initial button label, "Text”, is padded with blanks so the label graphic that is 
created will be large enough to accommodate the largest menu item label, "Key- 
board Equivalents”. This is really just a workaround for a toolkit bug. 

The menu callback simply prints the selected menu item label on the console. 

In an actual application the callback would probably use /sendtarget to call a 
method in some object associated with the menu. 

The following variation on the menu notify proc causes the menu's default to be 
changed to the menu item following the current choice every time a menu item 
is chosen. Since clicking on the abbreviated button chooses the default menu 
item, the effect of this code is to build an abbreviated menu button that steps 
through the menu choices sequentially. 











( 


% Hmm notify proc 
coM<3X^ <% ddXoctod.D 
t/valuot^ing 4 ixx2ex fprlntf 

/v^Xm 1 indoK flond 1 add 


% Honu vaXue + X 






dup /tnaxlocatioki 3 Indest send $rt { 


% Chock for ic^cXe 






pop d 






) 

V 


liiliMlii 

/aetdaf&ult 3 roxx send 







Analog Controls 

Sliders 

Sliders are a simple subclass of ClassDialControl. They implement a subset of 
OPEN LOOK sliders as described in the OPEN LOOK UI Specification. A slider 
only defines one delta, /Line. There's currently no way to show the users what 
the actual value of the slider is, because there is no way to display the scale. 
There are no tick marks, and there is no way to tell what the minimum and 
maximum values of the slider are. You can get some of this functionality if you 
are willing to write some postscript code. You will have to write some code to 
display the current, minimum and maximum values of the slider with numeric 
controls. But you will have to use a RexBag or your own subclass of QassBag 
to group them together in a reasonable way. 
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The following code will create and activate a slider: 



( % slider •«> - 

(Slider value ' 



%0 [ /value 4 -1 roll send ] printf 



} framebuffer /new ppenlookHorizontaXSXlder send 


% 


slider 


1 20 /setrange 3 index send 


% 


slider 


[/Line 11 /aetdelta 2 index send 


% 


slider 


1 /aetnormalization 2 index send 


% 


slider 


4 /setvaXue Z index send 


% 


slider 


10 30 610 /minsize 4 index send exch pop 


% 


slider 


/reshape 5 index send 
/activate 1 index send 


% 


slider 


/map 1 index send 


% 


slider 


/paint X index send 


% 


slider 



.% slider 



The slider's callback simply prints the current value of the slider. It could be 
modified to display the new value in a numeric control. 

Scrollbars 

ClassScrollbar is a descendant of ClassControl, and like all controls, has a target 
at which it directs certain actions. A typical target, or client, for a scrollbar is 
some sort of text canvas, a canvas that knows how to display text and scroll 
through it. A scrollbar must be given a target to scroll, a callback, and must 
have certain parameters (called deltas) set to values appropriate for that applica- 
tion (see below for an example). The scrollbar will handle painting itself, updat- 
ing its position and value, and will automatically call its callback when a change 
has occurred. It is the responsibility of the callback to inform the scrollbar's tar- 
get of the type of action that has occurred, e.g., scroll one line, or one page, or 
to the end of the document. 

ClassScrollbar is a subclass of ClassDialControl. It defines some new deltas 
appropriate to scrollbars. The scrollbar deltas are named /Line, /Page and 
/Document. They specify how much to increase or decrease the value of the 
scrollbar when a user selects a particular type of scrolling. For example, values 
for these deltas might be specified in units of lines, and so /Line would be set 
to 1, /Page would be the number of lines visible in a page, and /Document 
would be the number of lines in the document. These deltas are set by the 
scrollbar's target. 



Controls 



6-17 




Controls 



Scrollbars know how to scroll by lines, by pages, to absolute positions, and to 
the beginning and end of whatever's being scrolled. These types of scrolling 
correspond to motions defined by scrollbars. The motion names are /Line, 
/Page, /Document and /Absolute. 

When the scrollbar's callback is called, it should query the scrollbar for the type 
of motion that occurred with the /motion method, /motion returns a value and 
the motion name. The callback uses the value and the motion name to update 
the target appropriately. How the value is interpreted depends on the kind of 
motion. When the motion is /Absolute the value is the current value of the 
scrollbar and the target should arrange to scroll to that position. Otherwise, the 
value is either 1 or -1, depending on whether the scrollbar moved forward or 
backward, respectively, a line or page, or to the beginning or end of the docu- 
ment. 

There is another special purpose delta called /View. The scrollbar uses /View 
in conjunction with the /Document delta to display the proportion indicator. 
/View defaults to the current value of the /Page delta. 

While a scrollbar knows about its target, that target will often also want to 
know about its scrollbar. For instance, a text editor will want to update the 
SCTollbar's deltas whenever some lines have been inserted or delet^, or set a 
new value when some user action in the editor causes the document to be 
scrolled to a different place, e.g., searching. 

ClassScrollbar is an abstract class; that is, it is never instantiated itself, but rather 
is subclassed. To create a scrollbar, use OpenLookHorizontalScrollbar or Open- 
LookVerticalScrollbar. They are subclasses of ClassScrollbar, and all they do in 
the subclass is handle the OpenLook scrollbar look and feel. 
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Simple Scrollbar Example 



% Oxidate a acroXXbar with a callback. 

/scjToUbay ( % 5bar *•> 

r /lAOtion 1 indax aand 



% abar value nK>tion‘SiaHe 
% abar value 



/Absolute { /acrollabaolutely > 

/Line ( /ScxOllti^llnes ) 

/Page { /acrollbypages ) 

/Oocumant { 

dup eg ( 

/ scrolltbbegliwlng 

/acrolltoend 

} ifelse 

1 case 

/aendtarget 4 -1 roll Bmd 

) framebuffer /new OpehLookVerticalScrollbar aerxl def 



% ahar value roethodname 



/ScrolledObject Object [} 
claaabegin 

/ acrollabaolutely 
/acrQllbyllx:iea 
/acrpllbypagea 
/ acrolltobeglnnlng 
/aCrolltOend 
claaaend def 



{ pop (Abaolutely) ^ } def 
( pop (iby lines) ) def 
( pop <By pages) - ) def 
{ pop (To beginning) ** ) def 
( pop (To end) » ) def 



/foo /new ScrolledObject send def 

foo /aettarget scrollbar send 

100 100 20 300 /reshape scrollbar send 

/activate scrollbar send 

/map scrollbar send 

/paint scrollbar send 



This sample code uses a simple class called ScrolledObject, which understands 
methods for scrolling. This particular object defines methods which just print 
out a message saying that it was called, but in a real life application they would 
actually do something more useful. This example creates a scrollbar, then creates 
one of these scrolled objects, and makes it the target of the scrollbar. Then it 
just reshapes, activates, maps and paints the scrollbar. The callback for the 
scrollbar simply queries the scrollbar (which is passed as an argument to the 
callback) for the type of motion that occurred, and then performs a case 
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statennent to figure out what method to call, and then it sendtarget's that 
method to the scrollbar's target. 



Fields 

ClassTextControi 

A text control is a control whose value is a string. Text controls several 
methods of ClassControl; e.g., /CallNotify? and related methods do a string 
comparison rather than a simple 'eq' to determine if the value has changed since 
the last notification. 

A text control also registers its canvas as an input focus client; if it receives the 
focus, keystrokes are treated as characters to be inserted into the control's value. 
Certain keystrokes, such as backspace, cause other modifications to the control's 
value. The text control calls /checknotify (and thus /callnotify if the value has 
changed) whenever it loses the input focus, or when the RETURN key is 
pressed; it does not notify on each keystroke. 

Text controls are also selection clients. Thus they do not do tracking in the 
same way as other controls; they do not override the /EventHandler method, 
nor should subclassers do so. Instead they express a Selectable interest, and the 
global selection manager handles the appropriate tracking. Much of the code in 
ClassTextControi is for handling selections; writers of other text-selection code 
may wish to look at ClassTextControi for guidance. 

Read-only Text 

In addition to the enable/disable methods, it is possible to define a text control 
as being read-only. This has much the same effect as disabling the control, the 
main difference being how it paints. A disabled control may paint dimmed, 
whereas the read-only control paints normally but simply refuses to accept user 
input. 
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Methods: 

/setreadonly 



Operating on the Text 

Text controls offer several methods for programmatically altering the text string. 
The inherited method /setvalue replaced the entire string. The other methods 
operate at the current insertion point, which can be set by the user via the 
mouse, and can also be set programmatically by /setposition. (There is unfor- 
tunately no px)sition method; clients can obtain the current position by sending 
/Left, which yields the number of characters left of the caret.) 

In addition to modifying the text, clients can also change which character 
appears at the left edge of the control; characters further to the left are clipped. 
This can be used to scroll the text to keep the caret within the visible region. 
Many of the text-modifying methods conclude by sending /FitCaret, a subclasser 
method that can be overridden to specify that the caret should remain visible. 
The default /FitCaret never scrolls die text, but this is overridden by OpenLook- 
TextControl (see below). The client method /fitcaret calls /FitCaret with no 
other changes. 



Methods: 


/setposition 


/delword 


/fitcaret 


/scroll 


/inserttext 


/Left 


/delchar 


/Fitcaret 


/delspan 





Appearance 

The number of characters that can be displayed in a text control depends on the 
size it is given. The /minsize method for text controls requests a size based on 
the number of characters the control is expected to contain. The default is 5 
characters, but this can be changed for any given control (or for a subclass). 

Much of the visual behavior of a text control is inherited from ClassCanvas. 
Two methods of particular interest are listed here. 
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Methods: 

/setdisplaychars 

/settextparams 

/setcolors 



OpenLookTextControl 

The OPEN LOOK subclass of ClassTextControl adds no new client methods, but 
simply overrides some existing methods to provide OPEN LOOK functionality. 
Specifically, it paints scroll buttons when the text extends beyond the end of tihe 
control, it paints a line just under the baseline of the text, and it overrides 
/FitCaret to keep the caret visible after most operations. OpenLookTextControl 
is the default class for ClassTextControl; i.e., it is obtained by sending /newde- 
fault to ClassTextControl. 

OpenLookNumeric 

There is no "intrinsic” numeric control; there is only the OPEN LOOK form. A 
numeric control combines a text control with a pair of buttons that modify the 
numeric value by a specified increment, which is initially 1 but can be changed 
with /setincrement (If the increment is set to zero, the increment/decrement 
buttons are removed.) The /value of a numeric control is a PostScript number 
(integer or real). It is by default restricted to the range -32768 to +32767, but 
this range can be changed by calling /setrange (or the individual methods /set- 
min and /setmax). 

Non-numeric characters can be typed into the text control, but will result in the 
value being replaced with zero the next time the notifyproc is called. (This 
occurs the same as for any other text control: on the RETURN key or loss of 
input focus, if the contents have been changed.) 

Methods: 

/setincrement 

/setrange 

/setmin 

/setmax 
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Introduction 

Graphics are provided by the NeWS Development Environment as a packaging 
of a drawable object that knows how to reflect its state visually in an efficient 
manner. Graphics are designed to be very light weight so that they can be used 
as the images for buttons, menus, controls, and labels. There is no canvas associ- 
ated with a graphic, so using a graphic does not imply the overhead of a NeWS 
canvas object or of a QassCanvas object. 

Another characteristic that makes graphics lighter weight than canvases is that 
they do not establish or maintain the graphics context. Any operation on a 
graphic, including /setsize, /paint or /minsize, is sensitive to the current canvas 
and transformation matrix and is likely to permanently alter the graphics con- 
text by changing the color or font. Users should be aware of this and wrap any 
calls to graphics in a gsave/grestore when appropriate. On the other hand, if a 
series of calls to graphics are going to be made, as in the case of menus, it is 
necessaiy to do only a single gsave/grestore pair for the whole series. 
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Using OpenLookLabelGraphics 

Graphic instances are useful where a canvas interface is needed but a real 
instance of ClassCanvas is unnecessary. One example of this is labels on con- 
trols. By default the NeWS Development Environment controls do not come 
with lal^ls but it is easy to construct a control with a label by packaging them 
together in a bag. There is a special subclass of ClassGraphic called OpenLook- 
LabelGraphic that can be used just for this. Most common control labels are 
text so that is what we will use in this example. To create a label, you need to 
send /new to OpenLookLabelGraphic along with the thing you would like to 
display as the label. In this case it is the string ”My Label:”. 

Label;) /new OpenIxx>kLate 3ei:>d 




If you want to make your label use a different font than the default you can 
pass the font in with the string like this: 



Label:) /Helvetica findfcnt l2 scalefont] 
/new <)penX«oo]a.abelGraphic send 



You can also change the color of the label in a similar fashion. 



L^l:) ColorDiet /Green /new OpenL<x>kliabelGrd|^lc send 



J 



Now to complete the example we need to add the label to a bag along with a 
control. In this case I use an instance of an FlexBag to hold a label and a slider. 
I'll position the label to the left of the slider. Notice that I don't set the font or 
the color of the label; it will automatically inherit the text font and color from 
the bag. 
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/IfySag /i>ew Fie»B«g sand daf 

/Labal »eXf I»QSmO») 

t Labal;) /Halvetiqa findfont 20 soalafpntl 

/mins Isa 1 Indax send /setslse 3 Inde^ sand 
1 /addqliant MyBag send 
/SUdea: r/w {/a Fxavious POSITIONI 

(pop) frStoabuffar /new OpenloolcHoxrlS^ Sand 

0 0 300 20 /reshape 5 index send 
} /addcUent MyBag sand 



(> /satpalntproc J^Bag send 

10 10 /minslze l^Bag send /reshape %Bag sand 

/activate M^ag send 

/m^ i^Bag send 

/paint h^Bag send 



ClassGraphic 

The base class for all graphics is ClassGraphic. QassGraphic is an abstract super 
class. This means that ClassGraphic can not instantiated directly, rather Class- 
Graphic must be subclassed and then the subclass instantiated. ClassGraphic 
packages a number of useful utilities that a subclasser or user of a graphic 
might be interested in using. It is not necessary to use all of the features that are 
packaged in ClassGraphic when building a subclass. 

State 

One of the most commonly used features of ClassGraphic is "state". The state 
transitions in a graphic are designed to be painted as efficiently as possible. For 
example, if a menu item is highlighted by drawing a box around it, the graphic 
should be able to draw that box without re-drawing the text. There are a 
number of methods can be used to efficiently manage the state of the graphic. 
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Methods: 

/setinitstate 

/setstate 

/setelement 

/state 

/TranslateState 

/EquivelantState? 

/paint 

/Fix 

The states that a given graphic can reflect are completely up to the implementor 
of the graphic. There are two basics forms for the state supported by Class- 
Graphic, ^e state can be represented by any PostScript object type, or as an 
array of PostScript objects. The array case is provided as a convenience since it 
is a very common way of maintaining a number of axes of state (dependent or 
independent). Notice that since the graphic puts few restrictions on the form of 
the state, only graphics that understand the same states can be used inter- 
changeably. Graphic implementors are encouraged to describe the form of the 
state for their graphic above its definition. Objects that take graphics are also 
encouraged to publish the form of the state that they expect so that users know 
which types of graphics can be used with that object. 

Each graphic class will respond in a unique way to changes in graphic state. 
Therefore, graphics implementors must override methods that directly interpret 
the meaning of the graphic state. T3q>ically those methods are /Fix and /paint 
/Fix is called when some element of the graphic state is changed by a call to 
/setstate. It takes as an argument a single boolean or an array of booleans, 
depending on how many independent states the graphic has. Each value in the 
array indicates a change in the corresponding state in the state array. /Fix 
should use these booleans to update only those graphic elements that have been 
directly afected by the change in state. For instance, one element of graphic 
state might indicate that the graphic should have a highlighted border. When 
that state element is changed the graphic should just update the border and not 
completely repaint itself. This will r^uce the flashin the graphic as it changes 
state and increase the percieved speed of the update. 

The /paint method also must concern itself with the state, /paint is called when 
the graphic needs to be drawn completely. The graphic implementor should 
make sure that their /paint method reflects the current state of the graphic 
when it is done. 
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Graphics implementors may also need to override /EquivelantState?. 
/EquivelantState? is called by /setstate to see if the new state is different from 
the old state (it is called for each element of the array when the array form is 
used). This method should return "true" if the old state and the new state differ, 
it should return "false" if the states are the same. The default implementation for 
/EquivelantState? is: 




This will only work if the state elements are simple type (keywords, booleans, 
integers, etc.). If the state is represented by a more complex type (like a diction- 
ary), then /EquivalentState? will need to be overridden compare the old state 
and the new state appropriately. In the case of a dictionary, it may be appropri- 
ate to compare the two dictionaries element by element. Notice that 
/EquivalentState? does not need to be overridden for state maintained as an 
array of simple types since it is called for each element of the array. 

ClassGraphic does not initialize the state automatically, that is considered a 
subclasser's responsibility. The method /setinitstate should be called within 
/newinit to initialize the graphics state to one of its possible values. 

Size Negotiation 

ClassGraphic has a number of methods to support the manipulation of the size 
of the graphic as well as support for size negotiation. ClassGraphic is designed 
to work as a position independent object. That is that the graphdc will always 
render at the "currentpoint" (defined in the process's NeWS graphics state). 
Some users of graphics find it convenient to treat the graphic like a QassCanvas 
object for some operations (like positioning), so a number of ClassCanvas like 
position suppx)rt methods exist. In general, it is recommended that these 
methods be avoided. The following list of methods can be used for size negotia- 
tion: 
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Size Methods: 


Location Methods: 


/minisize 


/move 


/preferredsize 


/location 


/setsize 


/reshape 


/size 


/paintat 



The /minsize method is used to determine the smallest size that the graphic can 
be made. GassGraphic defines /minsize to return a width and height of zero, so 
graphic implementors should override /minsize to return the correct width and 
height for their graphics. GassGraphic does not attempt to enforce the 
minimum size, rather it is expected that users of the graphic will call /minsize 
and respect the returned values. This is a performance consideration bom of the 
fact that /minsize is typically a very complex function and should only be called 
when needed. The user of a graphic is in the best position to determine when 
they might violate the minimum size. 

The /preferredsize size method is similar to /minsize. /prefexredsize returns the 
width and height (larger than minsize) that the graphic can best be rendered at. 
For example, a scrollbar maybe able to be rendered so that some of its parts are 
not visible, it ideally it would like to be big enough to display all its parts and 
have some room to move. This size would be the scrollbar's preferred size. 
GassGraphic defines /preferredsize to return the minimum size. A graphic 
implementor should override /preferredsize if the graphic has a preferred size 
different from the minimum size. 

The size of the graphic can be set with the /setsize method. This method rarely 
needs to be overridden. There is no checking of the width and height arguments 
to ensure that they are larger than the minimum size. The user of the graphic is 
responsible for using reasonable arguments, /setsize has the side effect of 
invalidating the graphic (see validation below). 

The /size method will return the current width and height of the graphic. If /set- 
size has not been previously called the graphic's minimum size will be returned. 

The various location methods simple set, and retrieve the positional values that 
are the arguments (/reshape calls /setsize with the width and height arguments). 
These methods only perform a small subset of the functions of the similar 
methods in GassCanvas. There use is discouraged. 
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Rendering Support 

The various rendering support methods in QassGraphic are also commonly 
used. Graphics have a number drawing methods in common with ClassCanvas. 
The following methods and class variables can be used to support the rendering 
of a graphic: 



Methods: 


Class Variables: 


/paint 


/StrokeColor 


/Fix 


/TextColor 


/setthing 


/FillColor 


/thing 


/DisabledColor 


/thingatom 


/TextFamily 


/thingsequivalent? 


/TextSize 


/setterminal 


/TextEncoding 


/terminal? 


/TextFont 


/ThingSize 




/ShowThing 





ClassGraphic assumes that it is always rendered on a QassCanvas instance. 

This allows the various variables above to inherit their values from the canvas 
that they are rendered on. These variables can be used at any time as argu- 
ments to PostScript operators (ex. setcolor, setfont) or methods. Graphics imple- 
mentors can also choose to override the variables default behavior (getting their 
value from the canvas) by setting them to other values. Since these are well 
known names that users can change the defaults for in the UserProfile diction- 
ary, graphic implementors are encouraged to use them. 

The /paint and /Fix method have been discussed already. These are the two 
methods that get called to actually render the graphic, /paint should render the 
entire graphic including the elements of its current state. /Fix should do the 
most optimal job possible of painting the change in state indicated by its argu- 
ments. These methods should both render the graphic relative to the 
"currentpoint". When a user of a graphic calls either the /paint method or /set- 
state (/setstate will call /Fix) they should ensure that the current NeWS graphics 
state is correctly set up. The current point should be the location that the 
graphic is to be rendered at and the canvas should be the canvas that the 
graphic should be rendered on. 
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ClassGraphic supports a completely optional set of utilities for manipulating a 
"thing”. These methods are suppli^ solely as an aid to graphic implementors 
that which to use them. A "thing" is generally used to hold the user supplied 
part of the graphic. The graphics that are used in tNt menus for menu com- 
mand items, menu pullright items, and menu choice items all use 
ClassGraphic's thing support to hold the user supplied labels (usually strings). 

A thing is a simple specification that allows for a visible part, called the "atom" 
and some number of modifiers to affect the rendering of the atom. The thing 
specification looks like: 

atom, or [atom modifier modifier ...] 

An atom is either a string, executable array, instance of a graphic, or a canvas. 

A modifier is any number of a font, a color, a pair of numbers, or a name. 

The /setthing method can be called (typically in /newinit) to set the current 
"thing" for the graphic. The /thing method will return the current thing of the 
graphic. The /thingatom method will return the atom of the current thing of the 
graphic, /thingsequivalent? will compare its argument to see if it is equivalent 
to the current thing of the graphic. The two methods /ThingSize and /ShowTh- 
ing know how to parse a thing to return its width and height or to show it at 
the current point. These methods should be called from methods like /paint, /Fix 
or /minsize. 

The case where the atom is a string is the most common. The string is shown in 
the current font at the "currentpoint" such that the whole string is above and 
two the right of the current point when the CTM is the "defaultmatrix". The 
size of the thing is determined by the bounding box of the string. 

The executable array form of an atom is used to supply a drawing procedure 
for the atom. The executable array must take one argument on the stack, a name 
that is either /size, or /paint The executable array should return the width and 
the height that the drawing will occupy if the argument is /size. The image 
should be rendered in the current NeWS graphics state if the argument to the 
executable array is /paint The following is an example of the executable array 
form of an atom: 
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Notice that the array should assume that the current point, current color, etc., 
are available in the current NeWS graphics state. 

The atom of thing can also be another graphic. The /ThingSize method will 
query the graphic for its size by calling the graphic's /size method, so the user 
should ensure that the correct size for the graphic has been set. The /ShowTh- 
ing method will call the graphic's /paint method. 

The canvas for of the atom has not been implemented as of this writing. A can- 
vas can still be specified, but no bits will be rendered when /ShowThing is 
called. When /ThingSize is called on a thing with a canvas as its atom a width 
and height of zero will be returned. 

Most of the modifiers for a thing change the current graphics state in some way. 
A modifier that is a font will set the current font to new font. A color modifier 
will change the current color. Numeric modifiers need to be specified as a pair, 
they cause the current point to be moved relatively by numeric pair (x then y). 
The final modifier type is the name of a method in the graphic that the thing is 
passed to. This method is executed every time either /ThingSize or /ShowThing 
is called. Here are a few example of valid things: 

f ^ 

(tdat) 

[ (red test) 100 rgbcolor ] 

[ (offset red test) 10 0 ngbcolor 10 10 ] 

[ (red times test) /l^imesiloinazi flndfont 12 scalefont 10 0 z^bcolor ] 

V ) 
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The last two methods listed above, /setterminal and /tenninal? are used by the 
graphic user to determine whether a given graphic should be treated as a 
"thing" or should be treated as a stand alone graphic. The /terminal? method is 
used by the the NeWS Development Environment menu code to determine if a 
graphic should be used as a thing to one of the menu's graphic types or treated 
as the complete menu item. 

Validation 

ClassGraphic has a number of methods that are used to track and modify the 
current validity of the graphic for painting. 

The use of a /ShowThing is currently the only method of ClassGraphic that 
requires that an instance of its subclass be valid. Many of ClassGraphic's subc- 
lasses do take advantage of validation. The /validate method can be overridden 
to cache certain values in order to improve painting speed. One common use of 
validation is to cache the location of the "thing" relative to the current point for 
the current thing, size and font. The graphic is invalidated and then re-validated 
before the next time it is used. Deferring the validation until the time that the 
information is need allows for a number of operation that might invalidate the 
graphic to occur without having to validate the graphic each time. 

Methods 

/valid? 

/validate 

/?validate 

/invalidate 

/ValidateThing 



Building your own graphic 

Building a useful subclass of ClassGraphic is quite simple. The following exam- 
ple is a very simple graphic that has two states, either /Normal or 
/Highlighted. The graphic is a box that is filled a color that is specified as part 
of /new and is not outlined when the graphic is in its "/Normal" state and is 
outlined with a thick border when the graphic is in its "Highlighted" state. The 
initial state for this graphic will be "/Normal". 
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/newinit is overridden to consume the color argument to the graphic and to 
establish the initial state of the graphic. In this case, the state of the graphic is 
initialized by calling /setinitstate in /newinit with the name /Normal. Here is 
the code for /newinit: 




The second method that is overridden is /paint Notice that /paint checks to see 
what the current state is and otdy paints the highlighting box if it is needed. See 
the complete example 1 for the details of the /PaintColorFrame and 
/PaintColorInterior utilities. Here is the code for /paint (notice that super is not 
called): 




The /Fix method must also be completely overridden. /Fix will be called with a 
boolean that indicated whether the state has changed. The body of the /Fix 
method is wrapped in an "{ ... } if" so that no work is done if the argument to 
fix is "false". If file argument to /Fix is true then the state has changed and the 
new state needs to be reflected. In the code that follows the state is checked, if it 
is /Highlighted the the current color is set to the stoke color, if it is /Normal 
the current color is set to the fill color. Then the highlight frame is painted by 
the /PaintColorFrame utility (see Example 1 for the details of /PaintColor- 
Frame). Painting the highlight box in the fill color will have the effect or erasing 
just the highlight box. When fix is called the main color box is never re-drawn. 
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A m 

% Override: deeX with atate change 
/Fix { % )&ool - 

/atate aelf aend /Highlighted eg ( 

Highliig^tThickx^as StrokeColor 

iiiiiiiiii^^i^iiiiiiiiiiiiiiiiiiiiiiiiiiiii^iiiiiiiiiiiiii^ 

HighlightThicJcneaa FillColor 
) ifelae 
PaintColorFrame 

I if 

} def 





The override of /minsize in this example is very simple, it simply returns a 
width and height of "30". This value is fairly arbitrary. However, the minsize 
does need to be at least big enough to accommodate the colored box and the 
highlighting box. 

r 

% Override: min size 
/minsize ^ width height 

30 30 

} def 



The final method that must be overridden is /equivalent?. This is the method 
that is called when a user wants to compare this graphic and some other 
graphic that they might have (for example, a search method in a menu). Since 
this method has no default implementation in QassGraphic it must be provided 
by each subclass, /equivalent? needs to be carefully written since the graphic 
handed in may not understand the same methods as the graphic that is being 
implemented. In this case, another graphic is coiwidered equivalent to this 
graphic if the color handed into /new is the same. The /equivalent? first checks 
that the graphic handed in as an argument understands the correct methods, 
and then checks that the colors are the same. If either of these tests fail, the 
/equivalent? returns false. 
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% Override: true if oaroe Gra^diicColor, 

/equivalent? { % qraj^ic bool 

/Gra|)hiqColor /underatanda? 2 index aend ( 
/GrapbicColor exch aeixi 
Ora^lcGolor eq 



) ( 



) ifelae 



pep falae 



y def 



Methods: 

/newinit 

/paint 

/Fix 

/minsize 

/equivalent? 



Examples 

Example 1 contains the complete code for the graphic just described. The follow- 
ing code can be entered in an interactive session to try the graphic: 
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/can firaineJxUrifej; /xmt aL«i5aC«!nya9 aen<s <Jef 
^ 5 9calB 

ieo ^30 60 40 /reahape can aand 

^tleatora 

/activate can aenci 
/mp can s&ad 

faiae /aettranspar^t can aend 

/g i Q 0 rgbcolor 

/new Si»pXeCcior<&»phic aetwJ deOT 

can aetcanvaa 
5 5 movBto /paint ^ aend 
5 5 moveto /Highlighted /aetatate g aend 
5 5 noveto /Ko»mX /aetatate g aend 

greatoie 

/deattoy can aend /can null def 
/deatzey g aend /g null def 

V : J 

Example 2 contains a subclass of SimpleColorGraphic that supports the same 
states as the graphics required for the NeWS Development Environment menus 
and buttons. This graphic can be used in a tNt menu to build a color selection 
menu. The /newinit method for this graphic calls the /setterminal method with 
"true". This marks the graphic so that the menu or button will not try to treat it 
as a "thing", but will install it directly. 
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Example 2: Complete code for the SimpleColorGraphic 

r ^ 

% Statd id 2 /Normal or /Highlighted 

/SimpleColorGraphic ClasaGra|:*ic 
[/GraphioColorl claaahegin 

% Class Variables: 

/Ki^Xl^tllhickpess 2 def 

/Inset Hl^lightlliickness 1 add def 

% Methods: 

% Override: initialise color ^ state. 

/newinit f % color »> - 

/newinit super send 
/GraphioColor exch def 
/Normal /set init state self send 

} def 

% Override: Paint color £ border. 

/paint { % w -> w 

/state self send /Highlighted eg { 

HighlightThlckness StrOkeCOlor 
PaintColorFrame 

) if 

PaintColorInterior 

) def 

% Util; Paint border; preserve currentpoint 
/PaintColorFrame ( % thickness color ••> ^ 
setcolor setlinewidth 
currentpoint 

/size self send rect stroke 
moveto 

) def 

% tTtility: Paint interior 

/PaintColorInterior { % thickness color »> - 
Inset rmoveto 
/size self send 

Inset 2 imil sub exch Inset 2 mul sub exch 
rect 

GraphicOolor setcolor fill 

V I J 

(continued on next page) 
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% Ovs^rride; deal %rith state change 
/Fiac { % iDocl 

iiii^iiiiiiiiiiiiiiiiiiiiiB 

/state self send /Highlighted eg { 

Hl^llghtThlckneds StrokeColor 

Hi^llghtThlckness FlUColor 
) ifelse 
PalntColQxFrane 

iiiiiiiiiiiiiiiiiiiiiiiiiiiii 

% Ovenrldet min size 
/mlnslsie { ^ Width height 

% Overrid&; txm it aanie < 3 raphicColor* 

/egaivdil^t? ( % graphic «> bool 

/GraphicCoior /und^Stand?? 2 Indax sesndi 
/GairaphicColor ex<h d^nd 
GrephloCoIor eg 

iiiiiiiiiiiiiiiiiililis 

pop fald^ 

dlaaddhd def 

V . J 
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Example 3: OPEN LOOK compatible version of 
SimpleColorGraphic 

f \ 

% Modify Sl»|>XdCoXo«Gra|Aile handle ppenLook; 

% elanont StatQ array; 

% t /Highlightedl/MorinaX 

% /Enabled] /Dlaabled 

% /E^nphaplzed I /Normal 

% 1 

/OpenlOOkColOrOraphlc Eliif^leColotOtaif^io (] 
clasabegin 
% Claaa VariabXea: 

/finphaalzOThlcknesa 1 def 

^ Methods: 

% Override: Ad^uat fqr Olr'iiesa^ 

/neifittit { % color - 

/newiolt super send 
{/Normal /Enabled /Normal J 
/aetlnitatate self send 
true /settermlnal self send 

% Qmarride: Handle more complex state ^ 

/paint { %-««•>- 

/state self send 

di4> 0 get /Highlighted eq { 

HlghllghtThlckness StrokeColor 
PaintOplprFxame 

diup 2 get /Eh^aslZed eq t 

Bn^i^slxeThlckness StrokeColpr 
PalntColorframe 

j Ifelse 
pop 

PalntColorlnterlor 

% Override; handle more complex state 
/Fix { % {bool bool boolj - 
0 exch { 

/state self send 1 Index get 
1 Index /FalntState self send 

J 

(continued on next page) 
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} If 
X add 



) forall 

pop 

) def 

% Utility: R^>aint change state, 

/PaintState { % name ifhich »> - 

0 ( % /Highlighted or /Normal 

/Highlighted eq { 

HighlightnilcJcness StrokeColor 
PaintCoIorf^rame 

Higblightlhidcness FiXlCoXor 

FalntCoXorFrame 

State Z get /Etophasized eq { 

BnnphasizeXhickness StrokeColor 
PalntColorFrame 

|||||l|||||||||||||||||i^ 

) ifelse 

i;||||;||||il||||||||||||||^ 

1 ipop> % /Enabled or /Disabled; ignore! 

2 ( % /E^hasized or /Normal 

State 0 get /Highlighted eq {pop) { 

/^rphasized eq { 

Strc^eCOlor 

||||i|i|||||||||||i|i|:^ 

FlllOolor 
) ifelse 

EmphasizeiMckness exch 
PaintColorFrame 
) Ifelse 

) case 

) <tef 
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Introduction 

The basic NeWS input system, as described in the NeVJS Programmer's Guide, 
provides a complete mechanism for handling user inputs in PostScript applica- 
tions. However, it is defined at a fairly low level; the amount of detailed 
knowledge required to build applications at this level is daunting. Further, it 
has no relation to the class system in which the NeWS Development Environ- 
ment is built; this leads to inconsistencies and conflicts in the structure of appli- 
cations if both are used. 

A "class-based" layer of facilities has been built on top of the fundamental input 
and process primitives. This encapsulates many common forms of processing, 
and has a uniform style with the rest of the NeWS Development Environment 
class system. This layer comprises class hierarchies under three base classes: 
ClassEventMgr, ClassKeyboard, and Classinterest. QassEventMgr provides a 
process which expresses interests, awaits events which match those interests, 
and then dispatches to client handlers for those events. ClassKeyboard is a util- 
ity class which provides the definition of the keyboard attached to the server, 
along with a number of methods for inquiring and manipulating aspects of that 
definition. Classinterest itself provides a fairly thin veneer on the interests 
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defined by the server; it has a rich tree of subclasses which provide for a great 
deal of common input processing such as keyboard input and selections. 

The facilities described in this section are, in turn, used by higher-level com- 
ponents of the News Development Environment. For instance, many applica- 
tions which require keyboard input can get it conveniently via the OpenLook- 
TextControl. Even where the NeWS Development Environment does not pro- 
vide all the desired functionality, it is unlikely that the lowest-level facilities are 
the appropriate ones to use. The first few examples described in this chapter 
show ways to get straightforward keyboard input; check them before deciding 
whether you should master all the intervening material. 

For the simplest clients, there is no need to use an instance of Classinterest. 
Interests returned by the Makeinterest utility in QassCanvas are equally accept- 
able to an event manager. This level of use might be appropriate, for instance, 
for detecting button hits on a canvas, without reference to focus, selections, etc. 



Review of NeWS Input 

Let's briefly review the underlying server semantics for input. An input event is 
one of the "magic dictionary" objects (type /eventtype). It has a number of 
fields defined by the server, including Name, Action, Canvas, Process, KeyState, 
and TimeStamp; clients are free to add other fields just as though the event 
were a standard dictionary. Input events are generated by the server in 
response to hardware and window system activity (key presses, window cross- 
ings, etc.). Events are also generated by client processes running in NeWS. The 
server distributes an event by matching it against interests expressed by 
processes, where an interest is simply another event which has some of its 
Name, Action, and Canvas fields filled in with desired values. Interests may be 
directed at sets of values (rather than single values) by storing compound 
objects (arrays or dictionaries) in the relevant fields. 

The executable match facility is available and mentioned in the server documenta- 
tion, but receives relatively little emphasis. This is a central component of the 
NeWS Development Environment s subclasses of Classinterest, so we will 
describe it in some detail here. 
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Executable Matches 

When a dictionary appears in the Name, Action, or Canvas field of an interest, 
it specifies that an event will match any of a number of values (the keys in the 
dictionary). What happens when such a match is found depends on the value 
associated with the key in the dictionary. If the dictionary value is not execut- 
able, it replaces the value in the event being delivered. This form can be used, 
for example, to translate a key code into a character. But if the dictionary value 
is executable, the value in the field is not modified; instead the executable value 
is evaluated in the context of the awaitevent which receives the event. If more 
than one of those three fields has an executable match, all are evaluated; the 
order is Name, then Action, then Canvas. 

Let' s consider a simplified keyboard example. An event generated in response 
to a key press on the 'A' key will have a keycode in its Name field (e.g., 28493); 
its Action will be /DownTransition, and it will have null in its Canvas field. 



First consider how this would be handled without executable matches. The 
client might use an interest defined with 




That interest would be expressed in a process that then executed some code like 




The matched events will be returned by the awaitevent (with the keycode 
translated to a character); the client's KeyDown method consumes that event, 
and then the loop returns to the awaitevent. 
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An equivalent formulation using executable matches would use an interest like 



Name: 

Action; 

Canvas: 



dictf ... 
28493: $7 
,,, 3 



. % the keycode defined to A3Cii 'a' 



dict[ A)ownTran5itlon: {/KeyDown //inycanvaa aend) ] 
null 



and the event-processing loop is simply 




The translation from keycode to character happens the same way in both cases; 
but by convention an executable match consumes matched events. If there is 
more than one executable match in a single interest, the last (and only the last) 
should consume the event. It is important that there be no mixing of interests 
which use executable matches in the same process with those that don't; the 
stack discipline requires that a process use one or the other uniformly. 

The executable match style has some advantage in expressive clarity: the way a 
particular value is handled is closely associated with that value. It also ensures 
the system can provide handlers for events it needs to process, while allowing 
the client to add other events to be handled in the same process. For these rea- 
sons, all instances of ClassEventMgr require executable-match interests. 
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Main Class Hierarchies 

Now let's return to the three main classes involved in processing user inputs. 

ClassEventMgr 

ClassEventMgr is the NeWS Development Environment analogue of the 
forkeventmgr and ExpressEmgrInterests utilities. It provides for starting a pro- 
cess which will express a set of interests (/new, /clearcontext, /setname); adding 
and removing interests from the set managed by that process (/addclient, 
/addclients, /removeclient, /removeclients); and shutting down the event 
manager process (/destroy, /queuedestroy, /removeallclients). 

It also provides a set of inquiry methods (/name, /active?, /getprocess, /interests, 
/processstate), mechanisms for evaluating executable code in the event manager 
process (/callmanager, /argcallmanager), and support for a robust form of 
eventmgr, which is not killed by errors occurring in handlers for the events it is 
receiving (/makerobust). As mentioned above, any interest passed to an 
instance of ClassEventMgr must specify an executable match. 

ClassKeyboard 

ClassKeyboard provides the description of the server's keyboard — what keys 
are available on it, where the characters and modifier keys are, what escape 
sequences are associated with which function keys, etc. It also provides a 
number of utility methods to clients interested in keyboard processing; the most 
useful are /toChar, /toControI, /toControlChar, /toLower, /toMeta, /keyforsym- 
bol, /buildkeydict, and the pair /removefunctionkey and /restorefunctionkey. 

Classinterest 

Classlnterest and its subclasses are the NeWS Development Enviromnent analo- 
gue of the eventmgrinterest utility; they are the workhorses of input processing. 
It is possible to instantiate Classlnterest itself; the result is an interest little dif- 
ferent from that returned by createevent. Rather, most clients deal with subc- 
lasses of this class (both their own, and a few system-defined subclasses). 
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Branch Hierarchies 

There are two main branches to the class tree under Qasslnterest: ClassNo- 
tifylnterest and QassDependentInterest. They often occur in related groups. 
Both of these subclasses require that their instances specify executable matches 
(unlike Classinterest itself, which may or may not, at the client's convenience). 

ClassNotifyInterest 

A Notify interest matches an event which acts as a trigger or initiates a state. 

The two most common examples are assigiunent of focus to a particular canvas 
(ClassFocusSelfInterest) and detection of a mouse-button down or other event 
which initiates a selection-making dialogue (QassSelectable). The Notify 
interest may also detect the event which terminates the state it initiated; 
ClassFocusSelfInterest does, but QassSelectable does not. A Notify interest is 
normally handed to an eventmanager shortly after it is created, and remains 
active thereafter for the life of its client. 

Three other subclasses of QassNotifyInterest are less frequently used, but are 
provided for completeness. QassFocusSubtreeInterest triggers when focus is 
assigned to a canvas or any of its descendants in the window hierarchy. 
ClassEnterSelfInterest detects entry of the cursor directly into a particular canvas 
(whether or not this causes the canvas to become the input focus). QassEnter- 
Subtreelnterest detects entry of the cursor into a canvas or any of its descen- 
dants. 

ClassFocusSelfInterest has one additional side effect: when it is activated, it 
establishes its canvas as a focus client. That is, it tells the global focus manager 
that the canvas is interested in being sent focus events. If the canvas is a 
ClassCanvas, the FocusSelfInterest calls /setkeyconsumer (which in turn calls 
addfocusclient); otherwise it calls addfocusclient directly. The FocusSelfInterest 
likewise takes care of removing the canvas as a focus client when the interest is 
deactivated. Note that the other three subclasses do not register the canvas as a 
focus client. 
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ClassDependentInterest 

When a Notify interest is triggered (i.e., when an event arrives which matches 
the interest), one of the things the handler does is to express other interests 
which should only be active for the duration of the state initiated by the Notify 
interest. These transient interests MUST in turn be instances of some subclass of 
ClassDependentInterest. 

For a focus Notify interest, the dependent interests concern keyboard events, on 
both shift keys and those that directly produce characters. (These will be 
instances of ClassShiftInterest and QassKeyslnterest, respectively.) 

Dependents of a Selectable will handle mouse motion or crossing events, and 
button-up on the triggering button; these dependents are less structured than in 
the keyboard realm. 

Generally, a Dependentinterest will be global (i.e., it will be a pre-child interest 
on the root canvas), while a Notify interest will be expressed on a particular 
canvas. 

Keyboard Processing 

Keyboard processing is normally handled by instances of ClassFocusSelfInterest, 
ClassShiftInterest, and QassKeyslnterest. Straightforward keyboard clients are 
provided for in methods which hide almost all of the interrelations of these 
classes; see the first examples below. (For these purposes, a "straightforward 
keyboard client" is one which requires only ASCII characters off the standard 
typing array of the keyboard, in the usual shift combinations. By default, the 
usual shifts are Control, Shift, Meta, and CapsLock; Meta may be excluded from 
that set by defining /MetaKeys? to false in tire UserProfile diet at startup.) More 
sophisticated use involves deeper understanding of these classes, and is 
addressed in succeeding sections. 

There are two main sources of complication in handling keyboard input: 

The client should not get keyboard events when it is not the focus. However, 
when it becomes the focus, it should get events regardless of the cursor location. 
(Click-to-type will not work unless this criterion is met.) 

The interpretation of keys varies with the shift state, but different clients and 
different keyboards may require different definitions of which keys determine 
the shift state. For instance, emacs will almost certainly use the Meta keys, but 
other editors may apply other interpretations to those keys. 
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Similarly, some keyboards have a NumLock key which should change the right 
pad to ^ a numeric key-pad, but should not affect keys in the standard t)^ing 
array. 

A brief sketch of how keyboard events are delivered to clients will indicate how 
these problems are addressed. 

An instance of ClassFocusSelfInterest detects when the client's canvas has been 
assigned focus; until that happens, the client is uninterested in keyboard events. 
When the client gets focus, ttie focus Notify interest activates its associated Shift 
interests and Keys interests. A Shift interest determines the state of interesting 
shift keys when it is activated, and tracks up- and down- transitions on its shift 
keys to maintain that state as long as it is active. A Keys interest generally 
notices down-transitions on standard keys, translates them to characters, and 
delivers them to the client. The translation performed by a Keys interest is 
determined by the dictionary in its Name; when a Shift interest recognizes a 
change in the shift state, it causes new dictionaries to be stored in the Names of 
its associated Keys interests. When the client canvas loses focus, the dependent 
interests (Shift interests and Keys interests) are deactivated by the focus Notify 
interest. 

This second problem is addressed by the relationship of Shift interests and Keys 
interests. A Keys interest has an /update method that causes the interest to 
modify itself based on an externally provided state. The default behavior is that 
/update takes an integer and modifies the Name field of the interest based on 
that integer, as follows. 

When a Shift interest is activated, and again whenever the state of the shift keys 
changes, it reports the shift state to each of its associated Keys interests. Each 
Keys interest uses the shift state to index into an array of diets, and stores the 
selected diet into its Name field. The array of diets is precomputed so that the 
diet corresponding to a particular shift state will map keystations into ASCII 
characters according to that shift state. The result is that most keystrokes are 
converted directly into ASCII characters without having to examine the shift 
state on each keystroke; the additional work for handling shift keys is done only 
when the shift keys themselves change state. 

Multiple Keys interests may be associated with a single Shift interest, and multi- 
ple Shift interests may be associated with a single Notify interest. Methods are 
provided in each class for inserting and removing interests at each location in 
the hierarchy. 
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It is also possible for a Dependent interest to be activated independently, 
despite its name. This is primarily useful for a global Shift interest which main- 
tains a fully-defined shift state, without any associated Keys interests, for 
inquiries by random clients. 



Methods 

This section summarizes the interesting methods of these various classes. 
Methods for ClassKeyboard are discussed in a separate section. Two other data 
structures are crucial to the understanding of keyboard processing in the subc- 
lasses of Classinterest: the ShiftDict and Map. 

A ShiftDict is a dictionary that specifies how a shift state is computed from a set 
of keys; it associates device-keycodes to a bit in the shift state, or to some pro- 
cedure that does more complicated state maintenance. This is a little tricky; if 
you're going to build your own ShiftDict, see the full description below. 

A Map is a dictionary that carries some set of keycodes to values such as char- 
acters. At any time a Keys interest is active, its Name field will contain such a 
map. 

Each Keys interest has an associated set of Maps: an array of 2^ diets, where n 
is the number of bits in the shift state. If a shift-key transition is detected, the 
map corresponding to the new shift state is stored in the Name field; this is how 
different values are reported for the same key depending on shift state. 

Classinterest 

/new canvas action name /new interest 

Create a new instance of the class. 

/interest — /interest interest 

Analogous to /canvas in ClassCanvas; obtains 
the NeWS interest that corresponds to the Clas- 
sinterest. (Currently this is "self", but clients 
may use this method to isolate themselves in 
case the implementation changes.) 
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/activate 



/deactivate 



/Active? 



/destroy 



event /activate — 

Express the interest. Redundant (but safe) if 
already expressed. If the Process field in the 
interest is non-null, the interest is expressed for 
that process; otherwise it is expressed for the 
current process. The event argument is present 
because some subclasses require it, and callers 
may not know whether this particular interest 
belongs to such a class. If no useful event is 
available to hand to /activate, use nullevent. 

— /deactivate 

Revoke the interest. No-op if the interest has 
not been expressed. 

— /Active? bool 

Has this interest been activated (expressed)? 

— /destroy 

Automatically nulls out the Name, Action, and 
Canvas fields, to facilitate garbage collection. 



ClassNotifyInterest 

/Notifyin 



/NotifyOut 



/TestTrigger 



event /Notifyin — 

Activate all Dependent interests of this Notify 
interest. Generally called as part of an execut- 
able match in the Notify interest, so the trigger- 
ing event is on the stack. 

event /NotifyOut 

Deactivate all Dependents. No-op if they have 
not been activated. 

— /TestTrigger bool 

Tests whether the triggering event for this 
interest has already occurred. This is used when 
the Notify itself is activated, when it wants to 
determine if it should immediately activate its 
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Dependents. The default implementation for 
/TestTrigger is to return 'false'; it is overridden 
by subclassers. 

/f inddependent value /Enddependent Dependent true/false 

Find the Dependent interest (if any) registered 
using the given value. (See /adddependency 
below.) The /addsuite method in a Keys interest 
uses this method to avoid creating two identical 
Shift interests. 



ClassDependentlnterest 

/new any Hint canvas action name /new Dint 

/new null canvas action name /new Dint 

If a non-null Notify interest is provided, the 
Dependent interest is automatically registered 
with the Nint, in which case the "any" argument 
must be provided for use with /adddependency. 

/adddependency any Nint /adddependency 

Make this interest dependent on a specified 
Notify interest. The Dependent is first discon- 
nected from its current Notify, if any. The "any" 
is a value that can later be used to obtain the 
Dependent from the Notify using /finddepen- 
dent. If this Dependent is a Shift interest, it 
calls /adddependency for its associated Keys 
interests so that they will all be activated by the 
same Notify interest. 

/removedependency — /removedependency 

Disconnect this interest from its current Notify, 
if any. If this interest is a Shift interest, it calls 
/removedependency for its Keys interests as 
well. 
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ClassShiftInterest 

/new 



/destroyempty 

/shiftstate 

/modifierdown? 



ClassKeysInterest 

/new 



shiftdict Mint /new Sint 
This method is not often called by clients; 
instead. Shift interests are created by calling 
/addsuite for a QassKeysInterest (below). The 
/Action and /Canvas fields for a Shift interest 
are hard-wired. The shiftdict gets stored in the 
/Name field; if the diet is null, the default shifts 
(which may or may not include Meta, depend- 
ing on /MetaKeys? in UserProfile) are us^. The 
Notify interest can be null to create a global 
Shift interest. If it is non-null, the shiftdict is 
used as the "any" for /adddependency. 

— /destroyempty 

Destroy this Shift interest if it has no associated 
Keys interests. 

— /shiftstate int 

Return the current shift state of this interest. 

name /modifierdown? bool 

Return whether a given modifier is down, 
according to this interest. The argument is a 
name evaluated by sending it to the interest. 
Usually the name is a class variable. 
ClassShiftInterest defines class variables for 
these common shift names: /Shift, /Caps, /Con- 
trol, /Meta. 



downproc upproc maps shiftdict /new 
interest 

The usual interest fields are hard-wired. Name is 
initially null, to be updated when we hear from 
the Shift interest; Canvas is null because Keys 
interests are always global, etc. The client- 
supplied parameters are instead a proc to be 
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/addshift 



/remove shift 



/update 



/shiftstate 



/addsulte 



called when a key is seen to go down (null if 
none), another proc for keys going up, an array 
of Tn keymap diets, and a shiftdict to be used 
when building the Shift interest The keymaps 
and shiftdict can be null to get the correspond- 
ing defaults. Note that unwanted downprocs 
and upprocs should be null, not nullproc, for 
maximunt efficiency. 

Sint /addshift 

Link this interest with a particular Shift interest. 
The Keys is first disconnected from its current 
Shift, if any. The Shift tells you which Notify to 
hook up to (by calling /adddependency). 

— /removeshift 

Disconnect this interest from its current Shift, if 
any. 

int /update 

Update this interest based on the Shift's new 
state. The K^s interest selects the specified diet 
from the "maps" array supplied to /new, and 
stores the dictionary in the interest's Name field. 

— /shiftstate int 

Return the current shift state of the associated 
Shift interest. This method is provided for 
clients who let the Keys interest create the Shift 
(using the methods below), so the client has no 
handle by which to ask the Shift directly. 

notify-int /addsuite — 

Add a Keys interest to the structure under a 
given Notify interest. If the Notify already has a 
Shift interest that uses the shift diet given to the 
Keys' /new method, the Keys is added to that 
Shift. Otherwise a new Shift interest is created 
and added to the Notify, and the Keys is added 
to the new Shift. 
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/removesuite 



/defaultkeys 



/metakeys 



— - /removesuite — 

Unlink a Keys interest from its Notify/Shift 
structure. If this leaves the Shift with no Keys, 
the Shift is destroyed. 

downproc canvas /defaultkeys Nint 

This creates a Notify interest in input focus on 
the given canvas, and also a Keys interest with 
the given downproc and no upproc, using the 
default keymaps and shift diet. The Keys' 
/addsuite is called to create the Shift interest and 
hook everything together, and the NOTIPY 
interest (not the Keys) is returned. Thus, 
/defaultkeys is often called in a ClassCanvas's 
/Makeinterests method. 

downproc canvas /metakeys Nint 

Same as /defaultkeys, except it always includes 
the Meta shift keys rather than using the default 
specified via the User Profile /MetaKeys? 
boolean. 



Examples 

Example 1 : Simplest Keyboard Processing 

A client which needs only ASCII characters from the standard typing array of 
the keyboard has very little to do; it simply creates one more interest for its 
frame or canvas event manager to manage. This example, which uses the 
ReportChar procedure, extracts a character from the Name of an event and 
prints it on the current file. 
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The method /defaultkeys returns a single focus Notify interest. As a side effect 
of expressing that interest, the client's canvas is declared a focus client; that is, 
the global focus manager is told that the focus should be assigned to that canvas 
under the appropriate circumstances. Now, when focus is assigned to the client 
canvas, the Notify interest will activate default Shift and Keys interests. The 
first will track the state of the shift keys; the latter will translate keycodes to 
characters according to the current shift-state, and invoke ReportChar to handle 
those characters. ReportChar will be called with an event on the stack, which it 
consumes. 

The underl5dng mechanisms for all this are discussed below. 

Example 2: Adding Function Keys 

Suppose a client wants to receive function-key events, reported by the name of 
the key, as well as the simple ASCII characters. Let's re-write the first example 
to do this. 
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/KaiceXxxtdmdtd super send 

% Ao belTore# ww /defeultkeiya to cr^to u focus l^ottfy 
% end Include e siii^Xe escli Interest dependent on it. 

/PeportChar self soften J>ulldsend 

Canvas /defauXtteya ClassKeysXnterest send % 

^ Hov create another Keys interest* in function keys# 

% and add it to the saee Kotliy interest, 
dup % 

/Peport^^r^ction self soften buiidsend % 

null % 

{ /yKeyHaroes ClassKeytoard send % 

A^efaultKeyDlcts ClassKsyslnterest send A 

len^h 1 sub <dup) repeat ] % 

null /ne*r ClassKeyslnterest send % 

/addsulte erch send % 

) def 

V y 

The client now is using two private methods, /ReportChar and /ReportFimction, 
to respond to keyboard events. /ReportChar handles the default keys, while a 
second Keys interest is constructed to catch function-key events, and handle 
them with /ReportFimction. In both cases, the client wants only to see the key- 
presses; key-releases are uninteresting. The method /defaultkeys gives this 
behavior automatically. A general Keys interest, as created for the function 
keys, allows treating up and down transitions independently; passing null in 
place of a handler for either transition causes it to be ignored. 

We want this interest to share the default-keys interest's shift diet; but the shift 
state should not affect the reported values of the function keys. Therefore we 
construct a keymaps array by simply making enough copies of the same map. 
This map is the /FKeyNames diet supplied by ClassKeyboard, which maps key- 
codes to function-key names (like /FunctionFl); "enough" is determined by 
matching the size of the default keymaps array. The shift diet is "null", which 
results in this Keys interest using the same shift diet as /defaultkeys. 

Having created this second Keys interest, we tell it to insert itself as another 
dependent of the Notify interest returned by /defaultkeys; and Makeinterests 
returns just the Notify interest. Processing by the event manager is just as in 
Example 1. 
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Underlying Mechanisms of Examples 1 and 2 

The method /defaultkeys performs the following magic: 

1 . A Notify interest in focus directly in the client's canvas is created: 

f 

can /new ClassFocusSelflntezest send 

V 

This is special to /defaultkeys and /metakeys which are ordinary Keys. 
Interests do not create their own Notify interests. 

2. A Keys interest is created using the default keynaaps, and a diet is created 
when a DownTransition is received on any of the specified keys. 

3. A Shift interest in the default set of shift keys is created. 

The three interests are chained together, and the Notify interest is returned. 
When the ClassFocusSelflnterest is activated, it in turn declares the client canvas 
(can) to be a focus client: 

addfocusoXl^t -or- tm^ /aetkeyconsumer can 





(The latter is used if the canvas is a ClassCanvas. The method /setkeyconsumer 
in turn calls addfocusclient.) ClassFocusSelflnterest also calls removefocusclient 
(or false /setkeyconsumer) when deactivated. 

Sometime later, the user performs an action that assigns the focus to can (e.g., 
clicks in the window). A focus notification event is sent, and it matches the 
FocusSelfInterest. 

Executable match code in the FocusSelfInterest loops over its Dependents, send- 
ing /activate with the notification event to each. (In this case, there are two: the 
anonymous Keys interest and Shift interest created by /defaultkeys.) 
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The Shift interest's /activate method computes its shift state based on the event's 
KeyState, expresses the Shift interest, and sends /update with the shift state to 
each of its Keys interests. (There is only one of these in the first example: the 
one created by /defaultkeys. The second example also has the function-key 
interest attached to the same Shift interest.) 

The Keys interest's /update method uses the shift state to select an appropriate 
diet from its Maps and stores that in its Name field. 

Now a key-down on any of the standard keys will match the Keys interest; the 
diet in the Name field will translate the key code to the appropriate character 
(in the case selected by the current shift state), and the NeWS event mechanism 
will automatically store the translated value back into the event (NOT the 
interest). The diet in the Action field then causes the client's callback to be 
called with the translated event on the stack. 

If a shift-key transition comes through while these interests are active, 
executable-match code in the Shift interest recomputes its shift state and sends 
the new value with /update to the Keys, thus updating the translation diet in its 
Name field. 

The function-key interest is another Keys interest, which arrives at a similar 
object via a more explicit specification. 

The keymap that maps keycodes to names has already been computed by Class- 
Keyboard, so we simply share that. If we had desired instead to get the 
appropriate escape sequences, like "*[[224z" for the FI key, we could have used 
a parallel map, ^eyStrings. 

The Maps field of the interest is set to an array which consists of 16 copies of 
this diet (or 8, if MetaKeys? is false). Thus, tWs diet will be stored in the Name 
of the interest regardless of the state of the shift keys. The Action field is set to 
be a diet in which /DownTransition is defined to a proc that sends /Report- 
Function to the canvas. If a proc had been passed in place of the null argument 
to /new, /UpTransition would be defined to that proc; but as it is, there is only 
one entry in the diet. 

This Keys interest is associated with the same Notify and Shift interests as the 
first; it is activated, updated, and deactivated at the same time and with the 
same arguments. 
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Example 3: Reading the Number Pad 

The keyboard has a Num Lock key on the right keypad, which affects all the 
right-pad keys below the top row. The lock should be treated like Caps; one 
press sets it, the next clears it. (Also like Caps, it's a nnatter of taste whether it 
should take effect globally or on a per-window basis.) One way to get this is to 
define a shift state which has only 1 bit, and to track the Num Lock key exactly 
as the Caps key is tracked in the Shiftinterest code: 




Next we define a keymap with 17 entries, for the 17 keys on the right pad that 
should be affected by the Num Lock key: 



/JihiniK^aDlct 20 ^Ict <Jup 
{ 



/NhmPadEqual keyforsymibol 


(-> 


toChar 


/NumPad3laah keyforayndx)! 


(/> 


toChar 


/jhjwiPaciStar keyforaywboX 


(n 


toChar 


/NUzn^adMlnua kayfcaraymbol 


(-> 


toChar 


/UUmPad'7 kayfpriiynbQl 




m 


/HutnPad8 keyforayniMX 






/NUn^add kay£orayhd!>ol 




0) 


yHhmiPacUPXua kaytora^^nhoX 


(+> 




/Nu«il?ad4 kayforaynboX 






/NuinPad$ keyforayrnfeol 




0) 


/jihn^ad6 keyforayn*>oX 




W 


/NtsnPadl kayforaynbol 




m 


/NutnPad2 kayforayirbol 




(2) 


/lhaiitlPad3 kayforsynt>oX 




<3) 






kayfdtayrab6l 

/NvjiniPadO 

keyforsyinbol 

) /bullcDceydiqt ClaasKeyt^oarcl a^n4 



0 toChiar 



<0) 



toChar 

toChar 

toCihar 

toChar 

tcChar 

toChar 

toChar 

toChar 

toChar 

toChar 

toChar 
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The /buildkeydict method executes the proc in the context of QassKey- 
board, so keyforsymbol and toChar can be invoked directly. The {...} puts 
keycode/value pairs on the stack, and /buildkeydict then defines those pairs 
into the given diet. 

The other keymap, for use when NumLock is not set, has no entries, so we'll 
use nulldict in that position of the Maps array: 

f ^ 

/NuitiLockMaps tnulXclict def 

V 




Now, the following code would go in the canvas' Makelnterests: 



/RepoetChar self soften buildsend 

null MtunLocIcMaps NumShlftPlct 
/new ClassRieiysXntetest send 
dup /Priority 1 put 
/addsuite exch send 



The sense of all this is, ’’when the NumLock is set, accept and translate those 17 
keys to the characters given on key-down; otherwise ignore everything.” Rais- 
ing the priority prevents those keys from also being interpreted as function 
keys, in the function-key interest created earlier. 

Note that this Keys interest has a different Shift interest than the two defined 
above, although they are dependent on the same Notify interest. An alternative 
approach would have used a single shift diet (with 5 bits of state). However, 
this would have have required larger Maps arrays all around, and construction 
of a larger shift diet to cover all the possibilities. Either approach would be rea- 
sonable. 
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Example 4: Non-Standard Uses 

Now let's look at a simple example of non-standard usage. Suppose you want 
to have a pinball game that uses the shift keys to control the flippers. Thus you 
want to be notified of both down and up transitions on the shift keys, and don't 
care about any other keys. Moreover, you want to be notified directly about the 
shift keys, ra^er than having them modify the treatment of other keys. 

Here is the complete PostScript code for implementing the canvas, suitable for 
psh'ing. The discussion that follows will center on the keyboard-related aspects. 



% flippers *p5: creates e canvss thet It bAS the focus) flips 

% based Oh the state of the shift keys. 

/riipperCanvas cXassCanyas dictbegin 
/teft false def 
/Ri^t false def 

dieterd 

classbe^ih 

% <3ive this canvas a O-X O-'X oooxdlhate system. 
/Transfotn i 4 x y %r h ••> x' y* w' h 



4 2 roll 
translate 
scale 
0 0 11 



% w h X y 
% e h 

% w 



) def 



/PalntCanvas ( 

FillColpr /FillCanvas self send 
♦2 4.5 moveto left .X -'.I ifelse rlineto 
.0 .5 moveto ^.25 R10lt ,X ^,1 ifelse rllheto 
.025 setlinewidth 5txokeColor setCOlpr stroke 

/KeyHi^ dictbegin 

/leftShift /keyforsytiibol ClassKeyboard send /left def 
/Right3hlft /keyforsyrobol ClassKeyboard send /Ri#»t def 
dictend def 

/taakemterests { 

/Makelnterests super send 

self soften /new ClassFocusSelf Interest send % Hint 



(continued on next page ) 
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■■■ 

(tru6 /KeyBvetitI MI acitm 

tfalse /Ke;yEve[it!t aelf 9often bail<j|s9nd 

tKeyM^p] nuXXdict /new CX939JCeyBXi)t«»i»»t nmS % Nint nint Kint 
dup /Exclusivity false put 

/addsuitB eac<di send % Nizit 

i|ii|i||||i|||||||||||||||®^^^^ 

/KeyEvent ( ^ event bool -> - 

exch /Name exch def 
/paint 9elf 3end 

qlassend def 

/fti FlippetCanvas nullartey fteneibuffer /hewdefault CXaBsEaseFfane send def 

<Flippers> /setXabel fc send 
/activate f<? send 
/teshapeiJTOinuseir fc send 
/map f 0 send 

neuptocessgrcup 
curxentf lie closefile 

J 



All the keyboard information is concentrated in the methods /Makeinterests 
and /KeyEvent, and the /KeyMap dictionary. 

/KeyMap is defined using ClassKeyboard to translate the symbolic names /Left- 
Shift and /RightShift into the keystations specific to the user's hardware. The 
dictionary maps the key corresponding to /LeftShift into the name /Left, and 
similarly for /Right. 

In /Makeinterests, the canvas first creates a FocusSelfInterest, which will trigger 
whenever this canvas has the focus. (Again, when this interest is expressed, 
which is done automatically as part of /activate to the QassFrame, it will regis- 
ter the canvas as a focus client.) Then it creates a Keys interest and hangs it off 
the FocusSelfInterest (using /addsuite), so the Keys interest will be active when, 
and only when, the canvas has the focus. 
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The Keys interest itself is fairly simple. Since it is not using any shifts as 
"modifier keys", it uses nulldict as its shiftdict. Q^ote that this is not the same 
as using null, which would result in the Keys using a default shiftdict.) The 
Maps array has only a single map in it, since the shift state will always be zero. 
The map is the /KeyMap diet, which matches events involving the two shift 
keys. 

Thus, while this canvas has the focus, any transitions on the shift keys will 
match the Keys interest. The Name field in the event will be updated to contain 
either /Left or /Right. Then the Action (DownTransition or UpTransition) will 
cause either the downproc or the upproc to be called. These procs were con- 
structed via buildsend (defined in util.ps); they put a boolean on the stack to 
indicate the direction of the transition, then call /KeyEvent to extract the Name 
(/Left or /Right) from the event and store the boolean in the named instance 
variable. 

Complex Example 

Finally, here's a particularly complex example. Suppose you don't want the 
standard keys, but rather you want to see Ae F3 thru F7 function keys, going 
up as well as down, and (on them) you have the following requirements for 
sfuft-key processing: 

■ you don't care about the state of Shift or Caps 

■ you do want to distinguish Meta and Control 

■ Meta should be treated as a locking shift key 

Push it once, it's on; push it again, it's off. You also want these keys to "follow 
the mouse"; they should be delivered to you whenever the cursor is in your 
window, regardless of the focus. 

This example exercises most of the features of Qassinterest & ClassKeyboard, so 
let's just work it through all the way, with conunentary. 

First, assume you've established an event manager as before, either by creating 
it explicitly or by making your canvas a client of a BaseFrame. The next step is 
to arrange a Notify interest which is triggered by having the cursor in your 
window's subtree, independent of the focus: 
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The keys we're interested in will have different keycodes on different keyboards 
(or may not exist at all), so we need to ask QassKeyboaid's help in building a 
basic keymap. The /buildkeydict method was described in an earlier example. 



/fkoysO ^row«J>X0dtlct dxxp 

i /PMnotionF3 k»y£or«iyinb(^ . 

/r«ncti<«F4 keyfcr^ynibol /Fw»titoi>r4 
ke^otfaiyii4>ol 
/FunqtiQi^4 ki9yf0e|i;^iiib^ 

/FuDCtionF? k^o»yt«iboa. 

) /buildkeydict CIlaeeReybdexd 

^ 



On one keyboard, this defines the following diet: 









28424 t 






28426; 


/?i»ictionP4 




28428; 


/Futtctionrs 




28430; 


/FunctionF6 




28432: 


/FunctionF? 




V 




IIIIIIIM 





This gives us a diet for translating unshifted function keys. Suppose we want 
Control to override Meta ~ if control is down, it doesn't matter whether Meta is 
on or off. Then we need two more maps, which can be built conveniently from 
fkeysO: 
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(If we wanted the Control-Meta combination to be distinct, we'd need one more 
diet; as it is, we'll reuse fkeysC.) 

Finally, let's assemble these into a Maps array, for which Meta flips the 1-bit of 
the shift state, and Control the 2-bit: 







/fkeymaps t 




fk^ysO fkeyaM fkeysC fkeysC 




) 6 a £ 




^ 


y 



That completes the Maps array. But we also need a non-standard ShiftDict, to 
accommodate our differences from the default, again using /buildkeydict. 
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A reference to the code for ClassShiftlnterest may prove helpful here. 

The Meta keys tweak the 1-bit, and Control the 2-bit. The Shift interest handles 
simple on/off shift keys automatically; if the value associated with the key is an 
int (as is the "2” for /Control), the bit gets turned on/off depending on the new 
state of the key. (If more than one key controls the same bit, e.g., /LeftShift and 
/RightShift, then the bit is on if either key is down.) If the value is not an 
integer, it should be an executable array that computes some off-to-the-side 
information and then stores 0 in the Name of the event. 

LockChange is a utility in ClassShiftlnterest, which maintains up to 16 bits of 
locking-shift-state. It maintains the state on a per-window basis; converting it to 
have global effect is left, as an exercise, to the reader. (Hint: try demoting Lock- 
State from an instance- to a class- variable.) The executable matches on 
/LeftMeta and /RightMeta are constructed using the buildinterestsend utility in 
util.ps; the results procs extract the Shift interest from the event and send the 
/LodcChange method to it, giving "1” as the lock bit being changed. 
/LockChange also handles storing 0 into the Name field as mentioned above. 

Now that we've set things up, we'll actually create some interests using these 
diets, and make them available to the event manager. 









/fkl /myFKeyPrcx: (iup 


4 down AND up, 




fkeyiwps tghittdiot 






/nenf ClaasKeystAt^ttiidt 






def 

fni /addsulto fkl ^end 


% g«ft it built into m interest txiae 








^ 



We then pass fni back as part of a /Makeinteiests method, or hand it directly to 
an event manager (and call addfocusclient) as we did in the first examples. 
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introduction 

A selection is an indication of some data of interest to the user — almost 
always, some information visible on the screen which is about to be used in an 
operation. The most common example is text that is to be moved or copied 
from one place to another. Many other objects can be selected, and many 
operations besides move/copy are possible; for instance, a window may be 
selected so that its properties may be inquired or manipulated. The NeWS 
Development Environment provides a ClassSelection, whose instances (Selec- 
tions) describe such a selected chunk of data. 

The window system has a global registry which keeps track of a few selections; 
registering a selection causes any previously registered value to be deselected, 
and makes the current selection available to all clients of the window system. 
This registry is implemented inside ClassSelection, although its facilities are also 
accessible outside the class system, through utility procedures defined in sys- 
temdict. The registered selections are identified by a Rank, which may be any 
non-null PostScript object; the standard ranks are /PrimarySelection, /Secondar- 
ySelection, and /ShelfSelection. The ShelfSelection is also commonly referred to 
as the Clipboard. 

The instance variables for ClassSelection contain attributes of the selection. 

Some of these are required by ClassSelection's processing: Holder is the canvas 
responsible for the selection, and Rank is a global identifier, as described above. 
Others are attributes which support the user interface for making selections: 
Level is an integer indicating the “size" of the objects selected (for text, 0-4 
might indicate empty, character, word, line, and paragraph). The full set of UI 
selection attributes is detailed below. Finally, a Election usually also contains 
information stored by the client to identify the selection — e.g., for a text editor, 
either what the selection contents are, or how to contact the client with a query. 

There are two kinds of processing done with respect to selections: Making them 
and communicating their values. Inquiring the value of an existing selection is 
relatively easy (and common), so it will be addressed first. This section is pri- 
marily concerned with instances of some subclass of QassSelection. 

Making selections is somewhat more complicated, connected as it is to issues of 
user interface and UI independence. It gets a longer discussion, starting with 
the section "Making Selections.” This section deals both with Selections and 
with Selectables (instances of some subclass of ClassSelectable). 
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Finally, once a selection has been made, it must expect to have requests posed 
to it; the last section covers how to respond to such queries. 

Caveats 

It is important to recognize that a selection can exist without being registered in 
the global database — instances of (subclasses of) ClassSelection are used 
privately in several parts of the system before being made available to the world 
at large. 

Another important point is that much of the processing described in this docu- 
ment is initiated outside the application. For instance, global UI code will 
recognize that a function key has been released, or a Drag action performed, sig- 
naling that a selection transfer should take place. Similarly, the UI layer, not the 
application, is responsible for determining which user actions indicate a selec- 
tion is to be made or adjusted. This separation is maintained by defining Sub- 
ClassResponsibility methods in the low-level sennantic and UI superclasses, and 
requiring subclasses which actually get instantiated to implement those 
methods. 

One implication of this second point is that the Selection's methods will often be 
invoked in some foreign process (the global UI manager, or even in another 
client's process). They must, consequently, be self-contained — if they need 
some data such as the connection to the (Z-side client, that must be reachable 
from the Selection instance. 

One more cautionary note: In order to provide some separation between appli- 
cations and particular user interfaces (such as the OPEN LOOK user interface), 
a layer of indirection is inserted into the class structure for Selectables; clients 
create their own subclass of ClassSelectable by subclassing its defaultclass, not 
CLassSelectable itself, nor any particular UI's subclass of ClassSelectable. This is 
explained in more detail below. 
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Retrieving Selection Values 

Applications can retrieve the value of a selection by sending a message to it. 

This may require that the application first find that selection in the global regis- 
try. The relevant methods are 

rank /getselection Selection | null 

key /query false | value true 

request-diet /request response-diet 

There is a /getselection utility procedure in systemdict, which simply sends the 
/getselection message to Qass^lection. The single argument will normally be 
one of the Rank names given above, although, as mentioned, it may be any 
non-null PostScript object. If there is a selection currently registered under that 
rank, it is return^, else null. 

The other two methods above are sent to a Selection; /request is the more gen- 
eral (and complex). 

A single attribute of a selection can be retrieved most conveniently with the 
/query method. It takes the rmme of the attribute desired (e.g., /ContentsAscii), 
and returns the associated value and true, assuming there is such a value; if not, 
it simple returns false. 

/Request is defined to allow multiple requests, and requests with parameters. 
This may be preferable in several circumstances: when the request is an opera- 
tion which takes arguments, /request must be used. There is also a capability 
for requester and holder to negotiate the form of the requested data (describe 
below); this also requires use of /request. Finally, when the cost of communicat- 
ing with the holder of the selection is high (e.g. the holder must communicate 
with its C-side client through a slow communication link in order to respond to 
any request), it may be advantageous to batch queries in a single call to 
/request. 

The argument to /request is a dictionary which contains the complete request. 
Each key in the dictionary names a selection attribute or an operation the selec- 
tion should perform. For an operation, the corresponding value in the diction- 
ary may be a parameter or array of parameters; for requested attributes, the ori- 
ginal value in the dictionary doesn't matter. The selection will return a similar 
dictionary (or modified copy of the same dictionary, as convenient), with results 
and requested attributes in the value for each key wherever possible; if it cannot 
store a result, it will store the value /UnknownRequest. 



Selections 



9-3 




Selections 



The following fragments illustrate use of /query and /request: 



r 

% to reftrieve yist the characters of the selection 
/PrimaxySelection getselection null ne { % eel 






/ContentsAscii /qoeaiy 3 -1 roll send { 


% val 




. . .process the value. . . 

} ifeise % -- 


iiiiiliiiililiiiiiiii 




% a debugger night inquire of an editor idiere the selection 




% is in source file, so that it could set a bxea)q>oint there 

/PrimarySelection getselection dap null ne { % sel 




dictbegin% construct request diet 
/Filename null def 
/Startindex null def 






dictend 


% sel request 




/request 3 -1 roll send 
begin 

. . . process response . . . 


% response 




M ' such selection; 

} ifeise 


% null 











The set of request keys passed to the selection holder is open-ended; any set of 
clients that can agree on the interpretation of a new key, may use that key to 
communicate among themselves. A convention for the most common requests 
has not yet been established; but a number of the most useful are suggested 
here. In general, request names should develop parallel to the conventions of 
the XI 1 Window System, as documented in David Rosenthal's Inter-Client Com- 
munication Conventions Manual (to be distributed by the X Consortium). 

Most keys represent requests for the Selection to render its value in a named 
format. The most common of these is /ContentsAscii; others appear in the 
table. /ContentsAscii prescribes the selection rendered as a PostScript string, 
without text attributes (font, typeface, etc.). 
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Certain keys request that the client modify the selection in some way. Two 
"operation-type" keys are specified here: /DeleteContents and /ReplaceCon- 
tents. (Of course, other operations may be defined as clients agree on them.) 

/DeleteContents tells the client to delete the contents of the selection. Note that 
this is not the same as merely deselecting or destroying the Selection instance; 
e.g., in a text item /DeleteContents means remove the selected span of charac- 
ters from the text. Since there are no parameters required for this operation, 
either of /query or /request will work for it. Assuming the holder is willing and 
able to comply, a null value will be returned. 

/ReplaceContents involves a deletion, just like /DeleteContents; but then new 
data passed as an argument to the request should be stored in place of the 
deleted material, and the replacement should be selected. In this case (where 
the requester must be able to pass an argument to the request), the /query 
method will not work. Instead, the /request method is used, with a request diet 
for its argument. In the request diet, the key /ReplaceContents is defined, with 
the replacement contents as its value. This style of passing parameters enables a 
consistent interface to be maintained between requester and selection holder, 
regardless of the particular requests. 



NOTE , 



No Toolkit selections currently support (or attempt to use) the /ReplaceCon- 
tents request. It is specified here so that clients who may choose to imple- 
ment it will have a consistent protocol. The protocol described above 
matches that in the ICCCM. 



Since /query retrieves only one selection attribute at a time, the requester can 
easily control the order in which requests are processed. This is not so easy 
with /request: The order of objects in a dictionary is undefined, so if there is a 
required order to the requests, the requester must take special pains. It should 
define only one key in the request dictionary, /RequestS^uence, and its value 
should be an array. The 0th, 2nd, etc. elements of the array will be taken as 
requests, and the following (odd-numbered) element for each will be the 
corresponding parameter/value. In the diet returned by /request, the value 
associated with /RequestSequence will be an array in which the odd-numbered 
elements are the values returned by selection holder. 



A similar mechanism allows the requester and holder to negotiate over the form 
of response. The requester uses the key /RequestChoice, which is defined to an 
array similar to the one used with /RequestSequence. In this case, the keys in 
the even-numbered positions of the array are included in the order of the 
requester's preference. The holder may then choose any of the requests in the 
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RequestChoice to respond to; the key /RequestChoice is redefined to a new 
array containing the single key responded to and its corresponding value. If 
none of the choices is acceptable, the array should be replaced by /UnknownRe- 
quest. (If one of the choices in the /RequestChoice array is in turn a 
/RequestSequence, it is deemed responded to only if all the requests in the 
sequence are acceptable.) 



NOTE 



Like /ReplaceContents, the /RequestChoice key is not currently supported by 
the News Development Environment. Individual clients may choose to 
implement it if they are willing to run the risk of having their code become 
obsolete. 



The full details of request processing are described below under "Responding to 
Requests.” 



The following table summarizes the conventional request names currently pro- 
posed. Those keys marked with * are not currently implemented by The NeWS 
Development Environment, but are defined so that clients who wish to use such 
requests will have a common interface. Certain other keys, marked with 
AM implemented by some or all Toolkit selections, but are retained only for 
compatibility with the old "Lite” toolkit; their use is not encouraged. 



Name 


Argument 


Result 


/Canvas 


none 


The selected object, if it is a NeWS 
canvas. 


/ContentsAscii 


none 


A PostScript string containing the 
selected text, as described above. 


/ContentsPostScript 


none 


A PostScript object, which, when 
executed, will recreate the selected 
value. (This is likely to be most 
useful for graphical objects, which 
can be redrawn in a new environ- 
ment.) 


/DeleteContents 


none 


The contents of the selection are 
deleted, as described above. 
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Name 


Argument 


Result 


/Firstindex * 


none 


The count of how many objects of 
size Level precede the first object in 
the selection. 


/Level * 


none 


The multi-click level of the selec- 
tion; see discussion under "Making 
Selections", below. 


/Lastindex * 


none 


The count of how many objects of 
size Level precede the last such 
object in the selection. 


/RequestQioice * 


[request arg ...] 


A list of alternative requests (with 
parameters for each) of which the 
holder should respond to one, as 
described above. 


/RequestSequence 


[request arg ...] 


A list of requests (with parameters 
for each) which the holder should 
respond to in order, as described 
above. 


/SelectionObjsize ** 


none 


The size of the selection as meas- 
ured in units of Level 1; e.g., for 
text, the number of characters. 
Note the lower-case 's' in Objsize. 


/SelectionStartIndex ** 


none 


The count of how many units of 
Level 1 precede the first such unit 
in the selection. 


/SelectionLastIndex ** 


none 


The count of how many units of 
Level 1 precede the last such unit 
in the selection. 


/TransferSelection * 


dict[ ... /Source: 
Selection ...] 


One selection is requested to per- 
form a transfer between itself and 
another; see the note at the end of 
the next section. 
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When and How to Transfer a Selection Value 

Clients will occasionally decide on their own initiative that they should retrieve 
a selection value; for instance, the second example above would probably be 
triggered by invocation of a "Breakpoint” panel button or menu command. But 
most of the time, global user interface code will determine that a selection 
transfer is called for. If a client can accept input from the user (keystrokes or 
mouse drawings, for instance), then it should generally also be ready to accept 
the contents of a selection. Whenever the UI code determines this is appropri- 
ate, it will send an event to the destination of the transfer. 

This event's Name is /TransferSelection, and its Action is a diet describing the 
transfer that is to be made. The most interesting item in this diet will be the 
key /Source, which will be defined to the Selection whose value should be 
transferred. The event's Canvas is also significant: if it is null, the event has 
been "dropped off the cursor,” and the value should be inserted as close as pos- 
sible to the event's location. If the Canvas is non-null, the event was directed to 
the canvas, not a location; the value should be inserted at the canvas' most 
recent insertion point. Of course, some canvases may constrain all insertions to 
a particular location; for instance, a terminal emulator will probably be append- 
only. 

The NeWS Development Environment defines two subclasses of Classinterest 
which a client can instantiate in its /Makelnterests method, in order to receive 
and process /TransferSelection events. Transferinterest is an interest in a given 
canvas being the destination of a /TransferSelection event. The client supplies a 
method to be called when a transfer event is matched. 









/methodnaine /new Transferinterest send 


% Interest 




/methodnanie 


% event bool 




V 




J 



The client's method takes an event and a selection source. It leaves the event 
unchanged (it is there for examination if needed but should not be consumed). 

It consumes the selection in sending queries /requests to it to effect the transfer, 
and returns a boolean which is true if the client succeeded in the transfer. If the 
selection is not of a type acceptable to the client (if, for instance, all queries 
return /UnknownRequest), the client should return false. This will cause the 
event to be redistributed further up the canvas tree. 
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AsciiTransferlnterest is a special case of Transferlnterest for canvases that 
require simple text selections. If the selection does not respond to a request for 
/ContentsAscii, the AsciiTransferlnterest refuses to accept the transfer. If /Con- 
tentsAscii works, the resulting text is given to the client-supplied method. The 
client can also specify that the method must be called once per character instead 
of being called once with the entire string (by passing false as the third argu- 
ment of /new). 



g|||||||||||;;i||;||;|;|||x^ 






canvas /methodn 2 une strlngoX? /ndw AsciiTransferIntetKast sand 


% lx± 




/mothodname 


% evant string 








> 



Thus, most clients should never have to worry about constructing an interest in 
/TransferSelection, nor about terminating the transaction in which the selection 
is transferred. Typically it suffices to put a single line in your canvas's /Mak- 
elnterests method, such as: 



Canvajs /inserttext true 



/new jW3cilTxana£curlntere9t 9 end 



and then write a suitable /inseittext method (in this example, one that consumes 
a string). 

Clients which construct their own interest in /TransferSelection events must 
satisfy a few requirements: 

1 . When they receive such an event, they should make appropriate requests 
to the Source selection, just like clients using a Transferlnterest. 

2. If they cannot accept the selection, they must redistribute the /Transfer- 
Selection event themselves, to give ancestor canvases a chance to deal 
with it. 

3. If the transfer succeeds, the recipient should complete the transaction by 
sending a message to the UI code: 
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de3cir±ptiotb-<Jl<ft /tw«uifej:fini3hed C4-aasW omd Bend 



or 



deBcriptioft'^lct /tranaferfiniBhed MySeXectable Bend 



where MySelectable is any subclass of [/defaultclass ClassSelectable send]. The 
/transferfinished method requires the description-dict from the /TransferSelec- 
tion event's Action on the stack (and consumes it). This method is needed 
because only the recipient knows when it is finished with the transfer, and vari- 
ous cleanup actions (such as deleting the Source if the transfer is a Move vs a 
Copy, or unhighlighting the source, etc.) must wait until the transfer is over. 

Implementation note: It is possible for a Selection to be sent a /TransferSelec- 
tion request directly, rather than through an event. That is, a selection may 
receive a request whose key is /TransferSelection; the associated value will be a 
description-dict just like the one contained in the Action of a /TransferSelection 
event. In this case the Selection receiving the request is expected to insert the 
value at its current insertion point — there is no convention for passing specific 
coordinates. Since there is no UI code driving the transfer, the destination 
Selection must attend to other details: it should delete its own current value if 
its /PendingDelete? attribute is true; it should send a /DeleteContents request 
to the Source Selection if the key /DeleteSource? in the transfer description-dict 
is true; if either it or the Source has Rank of /SecondarySelection, it should send 
/deselect to that. This latter form of transfer is intended to handle operations 
such as exchanging two selections. However, no such requests are currently 
being generated by the Open Look UI manager, and no client Selections 
currently support such transfers. 
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Making Selections 

A selection client is a canvas which can contain a selection, or be one itself (e.g. 
a text window or a frame). The NeWS Development Environment provides util- 
ity classes to cover common text selection clients (DragTextSelectable) and also 
for the frame and icon windows for applications, which are selectable objects. 
Application programmers will want to avail themselves of these if possible; they 
are described at the end of this document. 

Other selection clients will subclass 2 classes: ClassSelection, introduced above, 
and (a subclass of) ClassSelectable, whose instances are interests in user actions. 
In both, there are SubClassResponsibility methods which the client must imple- 
ment in its own subclass. 

This discussion of making selections will probably be more intelligible after a 
high-level sketch of the protocol. Here is a typical sequence of op>erations for a 
selection-client application: 

■ The application creates a new Selectable. This is usually done inside a 
canvas's /Makeinterests method, so that the general canvas mechanism 
handles forking an event manager and expressing the interest (the Select- 
able). 

■ Ul-specific code inherited in the Selectable matches certain events (which 
events get matched depends on the particular UI), and decides a selection 
action has occurred. 

■ The Ul-specific code calls a SubClassResponsibility method (/newselec- 
tion); the client's Selectable subclass returns a new Selection of the 
appropriate class (i.e., the client's Selection subclass). 

■ The UI code then sets instance variables within that Selection to indicate 
what's going on (multiclick level, etc.). 

■ Next it calls more SubClassResponsibility methods to get the client to 
finish resolving the operation. E.g., the client might need to resolve 
mouse coordinates into a character index and then highlight the selected 
text. 

■ When the UI code decides that the user action is complete (e.g., a mouse 
button is released), it registers the Selection in the global dictionary so 
that other applications can access it. 
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Note that most of the goings-on are driven by the UI code. Clients need write 
relatively little code for their particular selections. In particular, clients should 
not try to interpret raw device events - some are not readily accessible to the 
client (/Copy key when the client holds the selection, but not the focus); most 
are subject to user-modification (some left-handers swap the meaning of the 
mouse buttons and function keys for left-handed use); and user interfaces are 
subject to many changes an application will do well to ignore if it can. 

Selections have been introduced already. There is more to be said about them, 
but first we consider Selectables. 

A Selectable is a Notifyinterest on a single canvas; it watches for some event in 
a small set which initiate making a selection (e.g., button-down on the Point or 
Adjust buttons). When an initiating event is seen, it expresses interests in other 
events like mouse motion and the corresponding button-up, and starts up some 
state machinery which implements the current user-interface for making selec- 
tions. It also causes creation of a new Selection, to be used in communicating to 
the client about the selection that is being made; see the /newselection method. 

The definition of a subclass of QassSelectable should be parameterized as fol- 
lows, to avoid wiring a particular User Interface into the application. 

r ^ ^ 

aqnclj 

{<in3t4noe var8>3 
qXassbeoin 

lili 



The SubClassResponsibility methods in a Selectable are: 



event rank holder 


/newselection 


selection 


event selection 


/selectat 


- 


event selection 


/adjustto 


- 


event selection 


/dragat 




event selection 


/dragto 


- 


event selection 


/inselection? 


bool 


event selection pos 


/attachinsertionpoint 


- 
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Again, most clients will also elaborate 

holder canvas type /newinit interest 
/destroy - 

The client makes a Selectable instance for each selectable canvas, typically by 
sending /new to a subclass of Selectable as part of the canvas's /Makeinterests 
method. The 'tfpe' parameter tells the global UI code what sort of UI to use for 
selections on this canvas. There are currently three types defined; others may 
be added as needed. (The UI manager will invoke some reasonable default 
behavior for any uiuecognized type.) The known t5rpes are: 

/Text Text within the canvas can be selected 

/Graphics Graphics objects within the canvas can be selected 

/Canvas The canvas itself can be selected (e.g., a frame) 

The holder should be a canvas which uniquely identifies this client; it will be the 
same as the Holder attribute of selections made in this canvas. It is used by 
ClassSelectable in an identity test, to determine whether an existing selection is 
held by this client. Normally, the holder and canvas arguments to /new will be 
the same. But if a single selection may exist in two or more canvases (e.g. a 
split view in a text editor, or several icons on the desktop), then the Selectables 
for those two canvases should have the same holder. This supports such 
behavior as starting a selection in one canvas of a split view and then extending 
it by clicking in the other canvas. 

When a Selectable interest is satisfied, its activation procedures will often start a 
new selection. This involves a send to the client's /newselection method, with 
appropriate rank and holder arguments. This method in the Selectable should 
create a new Selection instance (by sending /new to the client's subclass of 
ClassSelection). The returned instance gets its attributes filled in by the UI layer 
of Selectable, and is then passed back to the client in sends to its other Sub- 
ClassResponsibility methods. 

The other six SubQassResponsibility methods of a Selectable all take an event 
and a Selection instance. (One method also takes a third parameter.) The event 
is useful only for its coordinates - extracting the Coordinates array from an 
event automatically transforms them according to the current canvas and graph- 
ics context. The Selection contains all the other parameters of the method, as 
described later. The methods should operate as follows: 
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/select at event selection /selectat 

Resolve the coordinates of the event to an object, 
and start a selection on it with the given attri- 
butes. Note again that the Selection instance 
will already have been created via a separate 
call to /newselection. 

/adjustto event selection /adjustto 

Adjust the boundary of the given selection to lie 
on the object at the event's coordinates, again 
attending to the attributes in the selection. 

/dragat event selection /dragat 

Initiate user feedback for a Drag (direct- 
manipulation move or copy) of the given selec- 
tion; e.g., start an overlaid image of the value 
being dragged). If a grasp-point is needed (i.e., 
if the cursor coordinates are needed in order to 
position the feedback), use the coordinates of the 
given event. 

/dragto event selection /dragto 

Move a Drag-image so its grasp-point is at the 
coordinates of the given event, or give other 
feedback of a Drag in progress. 

/inselection? event selection /inselection? bool 

Return true or false as the location of the given 
event is, or is not, within the given selection. 
(The global UI code uses this to resolve multi- 
clicks or other special behavior resulting from 
clicking within an existing selection.) 

/attachinsertionpoint event selection 

postionname /attachinsertionpoint 

Not6 the specified point for later use as an inser- 
tion point if a value is copied to the selection. 

In particular, if this is a primary selection, the 
canvas should usually change its input focus 
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location. The positionname, together with the 
position of the event and the endpoints of the 
given Selection, are interpreted as for the /Com- 
puteNamedPosition utility, described later. 
Unlike the five other methods listed above, this 
one actually has a default implementation that 
simply ignores (pops) its arguments. 

Now we return to QassSelection, for the attri- 
butes used in the selection-making process. 

These are: 



Key (Name) 


Value Type 


Interpretation 


/Level 


int 


The "size" of objects to be selected. For 
instance, in text, 1 may indicate a character, 2 a 
word, 3 a line or sentence, etc. Essentially, for 
OPEN LOOK, Level is a multi-click count. 


/PendingDelete? 


bool 


True if the selection should be replaced by the 
next user input action (always, for primary 
selections in OPEN LOOK). 


/DeleteSource? 


bool 


Meaningful only if the selection is being passed 
to a /dragat or /dragto method, in wliich 
case the key is true if the operation is a Move 
rather than a Copy. 


/Pin 


any 


Tells the client where to "anchor” the selection 
during an /ad justto operation. The pin can 
be a name, in which case it can be evaluated 
using /ComputeNamedPosition (described 
below under "Utilities"), or it may be an arbi- 
trary value (typically an int) representing a 
previously computed anchor point. 
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Key (Name) 


Value Type 


Interpretation 


/Preview? 


bool 


True if the selection is still being adjusted by 
the user; when the user finishes (e.g., releases 
the mouse button), the client will get a last 
/selectat or /adjustto message with /Pre- 
view? set to false. Many clients will ignore 
/Preview?; it is provided as an accelerator for 
clients that wish to postpone moving some 
selection info to a more permanent location 
until the selection settles down. 


/Rank 


any 


Most selections have Rank eq /Primary Selec- 
tion. Selections made while some function-keys 
are down have Rank eq /SecondarySelection. 
(These get reflected differently, and have spe- 
cial uses.) The Clipboard has Rank eq /Shelf- 
Selection. Other Ranks are possible, though 
not currently used. 


/Registered? 


bool 


True if the selection has been registered in the 
global database via /setselection. 


/Hilited? 


bool 


This key is defined only if the Type of the 
Selectable which made the selection is /Can- 
vas. For these, it shows the previewed-state (as 
distinguished from the true state) of the selec- 
tion. E.g., Adjust-down on an icon [de]-hilites 
it immediately, and then toggles its hiliting as 
you slide off & on the icon. 


/Style 


any 


The style of highlighting recommended by the 
UI manager. Currently defined values are 
/Default, /Invert, /Outline, /StrikeThru, and 
/Underscore. Clients may ignore this value if 
they think it does not apply to their selection 
type, basing their highlighting instead on 
/^nk and /PendingDelete?. 



Finally, to assist clients in correctly reflecting 
changes to the selection, every time the 
/adjustto message is sent, the accompanying 
selection will have the name /Qianged defined 
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to an array of some of the above names; each 
key in the array has changed value since the 
previous adjustment. 

Notes: 

It is possible for an /adjustto to indicate a point 
outside the area in which contents can be 
displayed (e.g. off the bottom of a text window). 
This supports an auto-scroll feature, such as 
defined by the OPEN LOOK user interface. 
When an application gets such an /adjustto, it 
should (if possible) scroll some new data into 
the visible region from the hidden region indi- 
cated by the location of the /adjustto, and select 
everything up to that border. It should repeat 
this process as long as /adjustto messages con- 
tinue to be received. 




autoscroll doesn’t work yet — new 
messages are not generated. Clients 
willing to be obsoleted in the next 
release can repeat the scroll operation 
on their own until an /adjustto is 
received with coordinates inside the 
canvas, or with /Preview? set to false. 



Registering a New Selection; Unregistering an Old 
One 

When the UI layer decides that a selection specification has been completed, it 
sends /setselection to the Selection; the default implementation registers the 
instance in the global database. Clients may override /setselection if they need 
to adjust state or maintain any additional information when one of their selec- 
tions becomes publicly available. Of course, it is also possible for a client to 
create a new selection on its own initiative and send it /setselection; it will get 
registered just the same. 
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When a new selection is registered, any old selection already registered under 
that rank is sent a /deselect message, /deselect is a strict SubQassResponsibility 
method: there is no implementation in QassSelection. The subclasser's method 
should at least de-hilite the selection; most selections will also destroy them- 
selves. However, a deselected Selection might be retained, for instance to sup- 
port restoring the selection in an Undo operation. 

Just as a client may register a selection on its own initiative, it can unregister 
one by sending /unsetselection to it. A warning given above bears repeating 
here: It often happens that a /deselect message is generated in the client which 
is making a new selection (the cause of this one being deselected); the message- 
send in this context is in danger of communicating with the wrong client. For 
instance, printing data over currentprocess' stdout is likely to send it over the 
wrong connection. Clients must take care to store some access back to their 
generating client in selections they create, so they can communicate with it reli- 
ably when that selection receives a message while running in another process. 
Other messages that may be sent to a selection face analogous dangers: 
/singleiequest and /destroy in particular are liable to be sent to a selection while 
running in some process other than the selections' Holder's client. Equivalent 
care is required in these cases to respond in the proper context. 



Responding to Selection Requests 

Selections respond to requests through either of two methods: 

request-diet /request => response-diet 

oldval request-key /singlerequest => newval 



Subclassers must override AT LEAST ONE of these two methods. 

The first has been described from the requester's point of view above. The 
default implementation in QassSelection is in terms of /singlerequesfc the 
request-diet is enumerated with forall, and each request/value pair is passed to 
/singleiequest. (If /RequestSequence is found, it is passed to its own enumera- 
tor, which in turn calls /singleiequest When /RequestOtoice is implemented it 
will work similarly.) If a selection holder wishes to batch processing of 
requests, it should override the /request method. Any such override is then 
responsible for supporting /RequestSequence and /RequestChoice. 
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Instead of overriding /request, a subclasser may choose to override /singlere- 
quest. The key passed to a Selection's /singlerequest method identifies the 
nature of the request. Most keys represent requests for the Selection to render 
its value in a named format. For these requests, the value currently on the stack 
is to be discarded, and the client should put the requested value on the stack. 

Certain keys request that the client modify the selection in some way. For these 
requests, the oldval on the stack contains arguments, if any, to be used in the 
operation. Even if no arguments are needed, the /singlerequest method must 
be sure to remove the value from the stack; likewise, even if there is no return 
value, /singlerequest must store something (typically 'null') on the stack. This 
ensures a uniform interface to /singlerequest. (If neither the oldval nor the 
newval is meaningful, the oldval can simply be left on the stack as the returned 
value. See the /DeleteContents case in the example below.) 

For any request (value or action), the client may choose not to support the 
requested key. If so, /singlerequest should pop the oldval and return /Unk- 
nownRequest. 

Most clients will choose to override /singlerequest rather than /request, since 
the code is considerably simpler. A typical /singlerequest method might look 
like: 




/Binglerequedt { % oldval koy -> nowvaX 
{ /Content sAscil (pop Rank /GetValue Holder send) 

/SelectionObjsize {pop Rank /OetValue Holder aend length) 

/level {pop Level) 

/Canvas (pop Holder) 

/DeleteContents (Rank /DeleteSel Holder send) % leave junk val 
/Default {pop /UhknownRequest) 

) case 
) def 

V J 



Note that /singlerequest is not required to support /RequestSequence or 
/RequestChoice. Since clients making such requests must always go through 
the /request method (rather than /query), it is left to the /request method to 
handle breaking up the /RequestSequence or /RequestChoice into a series of 
calls to /singlerequest. 



Selections 



9-19 




Selections 



Utilities 

The News Development Environment defines five subclasses of particular 
interest to clients and/or implementors of selections. Two of these, Transferln- 
terest and AsciiTransferInterest, have been described above. The remaining 
three comprise two convenience subclasses of QassSelection, and a subclass of 
ClassSelectable which provides some of the basic functionality of selectable text. 

StaticSelection is a selection whose value never changes; it responds to queries 
by looking up the queried keys in a constant diet. When a selection is copied to 
the Clipboard, the UI manager sends /checkpoint to the Selection to obtain a 
static copy. The default /checkpoint method calls /Checkpoint, which in turn 
sends a /request to obtain the value of the selection in several formats, and 
stashes the results in a StaticSelection. Clients may override /checkpoint if they 
are willing to take responsibility for maintaining a static copy of their value. 

E.g., a text window might prefer not to copy a potentially large string to the 
Clipboard, but could instead cache the necessary pointers back to its data. 
However, if the text window's data subsequently changes, the text window 
must be sure that the static copy is not affected. If the static copy is about to 
become invalid, the text window can call /Checkpoint (mixed case) to fall back 
on creating a StaticSelection. 

StringSelection is a special case of StaticSelection that only knows how to render 
itself as ContentsAscii. This is to make it easy for clients to wrap a string inside 
a selection preparatory to handing it to a canvas via a /Transfer&lection 
request. (S^ /sendtocanvas, below.) A StringSelection is intended to be created 
directly via /new instead of via a ClassSelectable, and thus does not expect 
rank/holder arguments; its /new method takes just a string. 

DragTextSelectable provides assistance for clients whose selections are character 
strings, and who want to use an overlay canvas to display the selection during a 
drag-move or drag-copy operation. It Ms in the /dragat and /dragto methods 
for you. Subclassers will generally wish to override the /CxurentText method 
for greater efficiency (the default uses the normal /query mechanism, whereas 
individual subclasses can usually obtain the text by more direct methods). Sub- 
classers may also need to override /CurrentFont, if the TextFont of their 
Selection's Holder-canvas is not suitable. 
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Assorted utility methods: 

/ComputeNamedPosition { % first last current positionname => pos 



In ClassSelectable. First, last, current, and pos are numeric values refer- 
ring to the location of a selection (in the client's interpretation); first/last 
are the endpoints of an existing selection, while current is typically the 
position corresponding to the coordinates of a recent event. Position- 
name is one of the values defined for the /Pin in a Selection, and is 
interpreted as follows: 



/LowEnd 

/HighEnd 

/NearEnd 

/FarEnd 

/AtPoint 



the low end of the existing selection (first) 
the high end of the existing selection (last) 
whichever of first/last is closer to current 
whichever of first /last is further from current 
the cursor position (current) 



This is used for interpreting /attachinsertionpoint, and also for inter- 
preting the /Pin to establish one endpoint in preparation for subsequent 
/adjustto messages. 



/computepin { % first last current => pin-point 

In ClassSelection. If the Selection's /Pin is a name, /computepin calls 
/ComputeNamedPosition and stores the result as the new value of /Pin. 
Otherwise the previously computed /Pin value is returned unchanged. 
This should be done on every /selectat or /adjustto; the UI manager will 
override /Pin again if the anchor is to change. 

/computerange { % first last current => newfirst newlast 

In ClassSelection. Same as /computepin, but it returns the pinned posi- 
tion and the current position, in sorted order. 

/checkpoint { % rank => selection 



/Checkpoint { % rank => selection 

In ClassSelection. See earlier discussion re StaticSelection. 



/CanRenderAs { % - => namearray 

In ClassSelection. A list of names describing the formats in which the 
selection might be able to render itself. The list is used by /Checkpoint 
to decide the formats to install in the StaticSelection. It's okay for the list 
to include formats that the Selection in fact cannot handle; they'll just 
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get mapped to /UnknownRequest in the static copy. The default list is: 

/ContentsAscii /SelectionObjsize 

/ContentsPostScript /SelectionStartlndex 
/SelectionLastIndex 

Subclassers can override this to extend (or truncate) the list, so that 
stuffing their selections to the Clipboard will include all appropriate for- 
mats. NOTE: The list should NOT include /Canvas, even though the 
selection's /singlerequest method might handle such a request. This is 
because copying a /Canvas value to the ClipBoard can result in the can- 
vas staying on the screen after its application has been destroyed. 

/transferfinished { % tdict => - 

In [/defaultclass ClassUI send] (or any descendant thereof). Handles all 
cleanup following a transfer, such as deleting the source if the transfer 
was a Move, unhighlighting the source if appropriate, etc. 

Called automatically by Transferinterest and AsdiTransferlnterest, so 
most clients need not worry about it. 

/sendtocanvas { % canvas [delete?] => - 

In ClassSelection. Sends the selection to the given canvas via a 
/TransferSelection event. The selection need not be registered with the 
global manager. The optional bool says whether the selection should be 
deleted after the transfer. (Default is false.) The canvas can be null to 
send the event to the canvas(es) currently under the pointer. For exam- 
ple, the following would send a string to the current input focus: 

f ^ 

(random string) /new StrlngSelection send 
current input focus /sendtocanvas 3 -^1 roll send 

V J 
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/query { % key => value true 

% => false 

In ClassSelection. See discussion under Transferring & Querying. 

/getselection { % rank => sel | null 

In systemdict. Looks up the given rank in the global registry and 
returns the Selection (if any) currently registered for that rank. 

E.g., 

/clearselection { % rank => — 

In systemdict. Removes from the global registry the Selection (if any) 
currently registered for the given rank. 




Class Structure 

This section should be of interest only to UI implementors, i.e., people who 
want to supplant the Open Look UI manager with a different look and feel. All 
other readers may skip this part. 

Implementing a specific look and feel involves subclassing three classes: Clas- 
sUI, ClassSelectable, and ClassFunctionKey, This is the only time that those 
classes should be subclassed directly; normal clients should always subclass 
from [/defaultclass ClassXXXX send]. A look and feel implementor will sub- 
class ClassUI, then use that subclass as a mix-in when creating the other two 
subclasses. For example, ClassOLSelectable inherits from ClassSelectable and 
ClassOLUI. 

Having defined the three subclasses, you can install the new look and feel by 
sending /InstallUI to the subclass of ClassUI, e.g., /InstallUI ClassOLUI send. 
This builds three new subclasses: ClassSpecificUI is a subclass of the given sub- 
class of ClassUI. ClassSelectableUI inherits from the subclass of ClassSelectable, 
and similarly for ClassFunctionKeyUI. These three new subclasses are actually 



Selections 



9-23 




Selections 



the /defaultclasses for ClassUI, QassSelectable, and QassFunctionKey; thus they 
are the classes that all clients subclass from. 

(The function key portion of this hierarchy is beyond the scope of this docu- 
ment.) 

The purpose of the additional layer of subclassing is to enable a new look and 
feel to be installed in a running system. Redefining an existing class reuses the 
class dictionary, so every ClientSelectable's superclass pointer to QassSelecta- 
bleUI will always remain valid. 



Selection Example 

What follows is a lengthly example demonstrating how selections work in the 
NeWS Development Environment. Also included on the tape that this docu- 
ment was on is this selections example as an executable. On the tape the name 
of this example is selections-example.ps. 

Example 



% This id a ccxi^Iot^ application that deknonattataa anuOh of vihat'a involved in 
% supporting making/xnanipulating selections within a Canvas, the application 
% brings up two instances of a window containing a few circular subcanvases 
% (which scale automatically with the parent window) , 

% You can select circles by dragging out a bounding box that encloses the 
% CENTER of the desired circle. (It wouldn't be hard to add selection Of 
% single circles by clicking on there, but it %«ouldn't he ai^ more 
% instructive.) If you drag out a box using the '♦adjust*' mouse button, it 
% adds/zerooves the enclosed circles from an existing selection. 

% Per OPEN X(00IC, if you mouse down inside an esdsting selection and move the 
% mouse, it drags the selection tO a new location. (Holding down the CONTROL 
% key %ihiie you do this causes the selection to be copied instead of moved.) 

% You can drag between two different Circles Windows; you can also Use Cut and 
% paste. Secondary selections (quick-cof^/move) are NOT s^ported for this 
% example. 

% CcKwents throu^out the code explain how each piece fits into the 
% selection paradigm. 

: J 

(continued on next page ) 
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/Layout { 



/cli^tlist self send { 




dup /baggage self send 


% can (cx cy r] 


aload pop 3 1 roll 


% can r cx cy 


2 index sub exch 2 index sub exCh 


% can r X y 


3 -1 roll 2 mul dup 


% can X y w h 


/reshape 6 -1 roll send 





} forall 

) def 

% Overrida: Add select ipn-zelated Intexests^ ClrcleSelectable is the 
% Intetest in selection-causing events. Trensterintetest Is the 
% interest in being on the zeceiving dxl of a dtag or paste. Ihe 
% GlassFocusSelfIntezest is necessary so that we can become the input 
% focus, because the "paste* key sends a /TransferSelection event to 
% the focus, not to the window the mouse is Over. That is, the 
% Transferinterest will see a /TransferSelection event if it gets 
% sent to us, but we have to be the focus in order for the event to 
% get sent in the first plaoe. 

% If the ClassFocusSelflnterest were removed, the OEtLY effects would be 
% (a) the circles window would never take over the input focus, and 
% (b> you couldn^t paste circles into a circles window after deleting them. 

/Makeinterests { 

/Makelnterests super s«id 
self dup /Graphics /new Circle3electable send 
self /RecelveTransfer /new Transferinterest send 
self /new ClassfocusSelflnterest send 

% Toggle the selectedness of each child contained by the given xect. 

% This method is invoked from CircleSelectable . (It could have been 
% implemented directly in CircleSelectable, but since it needs to 
% invoke several methods of CirclesCanvas it is more efficient to 
% package them up as a single "send"; i.e,/ It's much faster to do 
% a single s^d that then does several ^self send"s. 
|||||||||||j^|||||||||||||||||||||||i|||:||||ii||:||||| 

% Note that ToggleSelection in turn sends to the individlual children to 
% change their selectedness; many selection clients, of course, do nob 
% have subcanvases and maintain all their selection state within a 
% single instance. See ClassTextControX for an example. 

|||||||||||§|||||||||||||||||||||||||;||||||||||||!i^^ 

/ToggleSelection ( % x y w h -> - 
/childzeni- self send { 

5 copy ChildInRect? { % x y w h child 

J 

(continued on next page) 
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/ToggXeState eawft 3 end 



) ( 



pop 



y ifeise 

) forall 
pop pop pop 



% X y w X) 



) def 



Petum troe it child I 3 contained by given tect, ke^ the example 
BiittpXe, m tetum tarue if the child ' 3 center i3 vitbln the rect, 
rather than testing for complete enclosure^ Qf course, this makes 
it Impossible to select just one of several concentric circles. 

But hey, it^s just a demo! 



% 

% 

% 

% 

% 

/ChildlnRect? { % X y V h child 
/baggage self send 
aload pop pop 
0.0001 dap xectsoverlap 

} def 



■> bool 

% X y w h {cx cy crj 
% X Y w h cx cy 



% Receive a selection via a /TransferSelection event. Transfer interest 
% <see /Makeinteiests) will call this method when such an event is seen. 

% we query the selection to see if it's a **Clrcles^ selection; if not, 

% we return false and TransferXnterest redistributes the event for us. 

% <B.g^, If ^ icon is dragged over a Circles window and released* it 
% will fall through to the desktop.) Assuming the selection IS Circles, 

% we add the circles to our canvas, trm:)slating them according to the 
% location of the ev^t, (We apply mln/max to 3ceep them from falling 
% outside the canvas, lest they be lost forever.) 

% NOTA BENS: The newly inserted circles do MOT end tp being selected. 

% If the operation was a Move*^ nothing ends up selected; if it was a 

% Copy, the source stays selected. Clients might well wish to select 

% the newly inserted stuff, but if the /BeceiveTransfer method were to 
% do this it could cause trouble if the operation is a Move, because the 
% global mechanism will subsequently try to delete the source Selection, 

% idiich might no longer exist! This is a recognised design deficiency 
% that will be addressed after the initial release. 

/ReceiveTransfer ( % event sel »*> event bool 

/Circles /query 3 -1 roll send { % event {circles) 

gsave 

Canvas setcanvas 

1 index /Coordinates get aload p<p % ev [circs] dx dy 

3 -1 roll { % dx ^ [X y r gray] 



(continued on next page) 
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V09 ^ ^0X1 

5 ttidex add 0.005 wax 0.995 win 
4 -1 roll 

4 indax add 0*005 wax 0,995 win 
4 2 Jcoll 

4 copr^ pop 0 360 azq extanddflraage 
ClrcXaChlld 5 array aatoacw 
null exdi /addcllent a^f aeaid % dx cfy 
} forall 
pop pop txue 



% dx <ly y r gray x 
% dx dy y r gray x' 

% dx dy r gray x' y 
% dx dy r gray x' y' 
% dx x^ y' r gray 





falae 

1 Ifelae 

classend def 

% Itext ¥6 have tha circular children thewaolvea. They use /SordarStroJce 
% to note irihether they*'re selected, by promoting a ncn-zero value^ (Note 
% that the value used is very small, because It^s interpreted on the parent's 
% 1x1 coordinate system.) A few sinple methods are provided for toggling 
% or clearing the selected state. The rest of the class has to do just 
% with implementing the circular border* 



/ClrcleOiild ClassCanvas nuUarray 
classbegln 



/Border5troke 0 def 



% promoted to O.Ol if selected 



/newinit ( % gray »> - 

/TiUColor exch dup dup rgbcolor promote 

) def 

/Selected? ( % - ^> bool 
BordexStroke Q ne 

/ToggleState { % - »> ^ 

/dorderStroke Selected? (unpromote) (.01 promote) ifeXse 
/paint self send 

/KlllSelectlon ( % ^ 

Selected? (ToggleState) if 

} def 
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% Override: Circiiiar border. Note that incoming x/y are lower left» not 
% center. 

/path { % X y V h - 

min 2 dlv 3 1 roll % r x y 

2 index add exqh 2 index add excdi % r qx qy 

3 -1 roll 0 36Q arc 

iilllllllllllllllllllllllll^ 

% Override. Default nethod aometimes auffera from roundoff errora. 

|||i||||i|||||||||||||||||||||||||||||||:| 

/StrokeCanvaa { % color Inset •> 

2 {neg dup /bbox self send insetxect /path self send) repeat 
pop setoolor eofill 

classend def 

% This is the guts of the selection stuff for this demo. For the most part 
% it just iirplements the required ’’SubClassResponsibility*' methods. There 
% are a couple utility methods at the end. 

/CircleSelectable I/defaultclass ClassSelectable s^tidj nullarrsy 
classbegin 

% Class Variables: 

% These three values are overridden vihen an operation is in progress 
% that involves an overlay canvas for feedback. The two operations 
% that do so are (1) bounding box for making/ad justing a selection, 

% and (2) dragging an existing selection to a new location. 



/OverlayCanvas null def 
/X null def 
/y null def 



% promoted when in use (bounding box and drags) 
% initial X of bounding box (promoted) 

% initial Y of bounding box (promoted) 



% Methods: 



% Subclass responsibility: Create an instance of our subclass of 
% GlassSelection. No special initialisation is required. 

% Note that, as with the other subclass responsibility methods, this 
% demo code does not itself contain any sends to the /newselection 
% method. CircleSelectable INHERITS code that, having decided that 
% a particular user action should be interpreted as starting a new 
% selection, then does ^/newselection self send**, thereby calling the 
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% jnethoa below. 

/newselection { % event rank holder •*> selection 
/new CircleSelection send 
oxch pop 

% Subclass responsibility: Update a CircleSelection instance to reflect 
% the start of a new selection. For our purposes this is treated the 
% san« as when we start adjusting an old selection, so we share the 
% code with that method. 

/soloctat { % event selection **> - 
/adjustto self send 



Subclass responsibility: tJpdate a CircleSelectlcm instance to reflect 
a new selection action. Many of the variables in the Selection carry 
infoxniation passed to us from the global UZ qode» In particular, if 
/^review? Is true^ then the user is still marking the selection, and 
we don't need to change anything exc^t the bounding~box feedback. 

(If we wanted to get fancy, we could adjust the highlighting of the 
circles on the screen but not actually change whether they're selected 
yet, but let's not be fancy.) If /Preview? is false, the operation is 
over and it's time to change the state of the affected canvases. 



% 

% 

% 

% 

% 

% 

% 

% 

% 

% Note that we support only PrimaxySelecticxi; if we're asked to make a 
% SecondarySelection we ignore the request and leave the selection empty, 

% As mentioned earlier, when the operation is finished (Prevlew^f alse) , 

% we use a method In CirclesCanvas to do the actual toggling, to avoid 
% doing too many cross-instance sends. 

/adjustto ( % event selection -> 

/Rank 1 index send /PrlmarySelection ne { 
pop pop 



} { 



OverlayCanvas null eq ( 

1 index Canvas StartOverlay 
) if 

exch EventCoords X Y points2rect % sel x y w h 

/Preview? 6 roll send ( % x y w h 

gsave 

OverlavCanvas setoffl^vas erasepage 
0 setgray 0 setllnewidth xectpath stroke 

grestore 
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i { 



% X y w h 



EridOverX^ 

/ToggleS^lectioii Cwvas send 



y Ifoise 



) ifelsd 



) aef 



% iSuibdless zesponsibilityt Hhen a drag operation begins we ;)ust remember 
% the initial coords and create the overlay, Kote the overlay covers the 
% whole framebuffer (unlike in /adjustto) ^ but the coords are in our own 
% CM, Wb use a temp event^s Coords in /dragto to convert between them. 

/dragat ( % event selection •> ** 

pqp fram^mffer 3tartOverlay 

) def 



Hote that we don't actually perform the transfer operation here; 
/dragat and /dragto are mainly involved in feedback to the user. 

Ihe /TransferSelectipn event is generated by the global UI ma<diinery. 



% Subclass responsibility; Clive feedback for the drag in progress. 

% won't try to do anything fancy like showing the actual circles 
% (hard to decide how to scale them anyway when moving between windows) ; 
% we just draw a line from where the drag started to the current point, 

% Wten /^review? is false^. the operation, is over, so we tell the 
% selection to remember the offset %iAiere the drag began (we could've 
% done that in /dragat instead) . 

% 

% 

% 

/dragto { % event selection •> ^ 

/Preview? 1 index send ( 

gsave 

% Ose a tenporary ev^t to convert X/f from the original 
% canvas's CW to that of the overlay. 

Canvas setcanvas 

createevent dup /Coordinates [X Y) put 
OverlayCanvas setcanvas 
/Coordinates get aload pop 
erasepage 0 setgray 0 setlinewidth moveto 
/Coordinates get aload pop lineto stroke 
grestore 

iiiiiiiliiiiiiiiiiiiiiiiiiiiiiiiii 

X Y /SetDeltas 4 
pop 

EndOverlay 
) ifelse 



roll send 



% ev evtenp 
% ev evtenp 
% ev x' y' 

% ev 



% ev 
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% Subclass responsibility: Normally we'd extract the coordinates from 
% the given event and see If they're Inside the given selection. But 
% in this demo we have the advantage of knowing that the selected 
% objects are canvases, so we can let NSHS do a lot Of the work for 
% US by using canvasesunderpoint . As before, note that we uniformly 
% return "false’* if the selection is not Primary, 

/inselection? { % event selecti<»fi -> - 

/Ranh exch send exch pop false ex<^ % false rank 

/PrlmarySelection eq { 

null c2uivasesunderpoint ( % false can 

% Look for canvas whose par«it is the CirclesCanvas ^ 
dup /Parent get Canvas eq ( 

% Found it: Is it selected? In any case, exit the loop 
/Selected? exch send or 

) ifelse % in? 

} forall 

% Civen an event, obtain its X/Y in our canvas's coordinate space. 

/EventCoords { % event -> x y 
gsave 

Canvas setcanvas 
/Coordinates get aload pop 

gxestore 

% start an operation that uses an overlay canvas. The overlay sits on 
% either our own canvas or the whole framebuffer. This method also 
% obtains the coordinates from the initiating event (using our canvas 
% for the CTM) and stashes than for later use. 

/StartOverlay ( % event canvas *-> - 

createoverlay /OverlayCanvas exch prcmote % event 

EventCoords /Y exch promote /X exch prcmote 



% Clean up after an overlay operatioi. 
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/]SSndOver;Lay { % - •> - 

^sav^ Ovarla^Canvad {latcamraa ^raatox^a 

/Qverla^Canvaa unpxonQte /X unpzomotft /Y unpromote 

) 

claaaend 

% lAie ClaaaSalaction aubclaaa again ii<[|>Xero 0 nta the tegulxed mathods , 

% cSoBwoniy these are iinpXeeentecl by abort bits of code that simply 
% call similar methods in the Canvas (which is available as the /Holder 
% instance variable In roost Seleoticnsy ^ Heze< though, the operations 
% are simple enooch that most of the worh is done directly, 

/CixcleHelection ClassSelection nullarray 
classbegln 

% Overrider This class variable tells the gi<^i machinery nhat forms 
% of query to stash away when copying one of our selections to the 
% clipboard (i,e^r for* cut & paste) ,r 

/CanHetnderAs [/CirClesl def 

% The following methods are promoted to constants when a drag operation 
% is performed. The defaults normalise all the selected circles to be 
% at 0^0 (vhich is then offset by the location of the *"get" action) , 

% When a drag is performed^ the prba>ted constants cause the destination 
% coords to be Interpreted relative to the starting point of the drag. 

/DeltaH (dup) def % Offset due tO drag (promoted) 

/DeltaY (dup) def % ditto 

% Subclass responsibility: Hemove all circles from this selection, 

% thereby dehighlighting them, Ve do this by asking our Holder (the 
% circlesCanvas) for a list of its Children, and then telling each 
% child to deselect Itself, 

/deselect ( %-•»>-- 

Rank /PriinarySelection eq { 

/children+ Holder send { 

/KlllSelection each send 

} forall 

) liT 

/DeltaX unpromote /DeltaY imprcroote 

J def 

% Get a list of the CircleChild canvases that axe selected in our 

V Z_ J 
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% canvas^ Thia ia a ^lUty \ise<X by /slngiejaequeat* Hot© that the 
% Ust ia always awpty if thla la not a PrliwarySelecstlon. 

/Sei©ot©(iShll<Jr©n ^ (cfflivaaes] 

( tlank /PrimazySeXection ©q { 

/childsen+ Holder aend ( 

/Selected? 1 index, send not {pop) if 

) fozall 

% sujxJlasa reaponslhllity; The only negneata we upxJeratand are (1) 

% render the selection as an array of circles, (2) render it as a 
% single canvas <the parent) , and ( 3 ) delete the selected canvases 
% frcw the CirclesCanvas parent. 

||||||||||||ii|||:;||||||||||;i|||||||||||||||;i 

% por the first/ we offset the x/y of each circle according to PeltaX/y, 

% Xf those methods have not been promoted/ this causes each circle to be 
% given a 0/0 origin, udiich is then offset by the destination coords < 

% If /SetPeltas has been called# DeltaX/f offset the circles by the 
% starting coordinates of the drag operation. 

% Ihe second form of gnery, /Canvas, ish^t by any means reguired;i 
% indeed# there are few if any clients who query for such a value < Hut 
% it's so trivial to provide that most Selections might as well offer it, 

% Note however that it is HQT included in the /<PBnRend6rAs array, lest 
% the /Canvas value get copied tc th© dipBoard and thus prevent th© 

% window from going away in a timely fashion. 

iiiiiiiiiiiisiiiiiiiiiiiiiiiiiilliiiixiiiliiiiiiiliiiii 

% For /IteleteContents, we use th© tridt of turning th© to-be-deleted 
% canvas (es) <^que just before deleting them, to force that portion 
% of th© parent to be repainted* Other selection clients might be able 
% to make more precise calculations of what needs to be repainted. 

/singlerequest { % oldval key -> newvai 

iiliiiiillllllllllliiliiiiiiililillli 

/Circles I 

pop t SelectedOhildren ( 

dup /baggage Holder seiid aloed pop 
/PillColor & -1 roll send 
colorrgb pop pop % x y r gray 

4 -1 roll Deltax sub 
4 -1 roll Deltay sub 
4 a roll 4 array astoxe 
} fprall ) 

. y 
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a 

/Canvas { 

pop Holder 

llllllllllllllllillliiililiililli^ 

/DeleteContents ( 

SelectedChlldren { 

false /settranspatent 2 index send % force daiftage 
/removBclient Holder send { /destroy exch send ) if 

) forall 

) 

/Default ( pop /OnknownRequest > 

\ case 
} de£ 

% Stash the starting coordinates of a drag <^?eration. 

/SetDeltas { % x y - 

/DeltaY exch proiaote 

/DeltaX exch promote 

) def 

class€Kid def 

% Finally/ here's the code to fire up the windows. 

/cl CirclesCanvas nullarray framebuffer /ne%#default ClassBaseFrame send def 
(Selection Exan^le) /setlabel cl send 
(SelDemo) /seticonlabel cl send 

/c2 CirclesCanvas nullarray framebuffer /newdefault ClassBaseFrame send def 
(More Selections J) /setlabel c2 send 
(SelDemo) /seticonlabel c2 send 

/activate cl send /activate c2 send 

/place cl send /place c2 send 

/map cl send /map c2 send 

% Because both windows were fired up from the same process/ they share 
% the userdict that contains /cl and /c2. Therefore neither window will go 
% away until both have been told to Quit. (Hhen both processes have been 
% Killed/ the userdict will go away.) To avoid this problenv we tell 
% each frame's EventMgr to put a copy of the frame on the stack/ then get 
% rid of the copies in userdict. 

{cl /cl null def) /callroanager /EventMgr cl send send 
(c2 /c2 null def) /callmanager /Eventb^r c2 send s^d 

J 

(continued on next page) 



Selections 



9-35 





10. MISCELLANEOUS TOPICS 



10. MISCELLANEOUS TOPICS 




Miscellaneous Topics 



Miscellaneous Topics io-i 

ClassTarget 10-1 

■ Setting and Getting the Target 10-1 

■ Sending to the Target 10-2 

■ Example 1 0-2 

■ Automatic Menu Targets 10-3 

■ Disappearing Targets 10-3 

■ How Targets Work 10-3 

News Development Environment Applications 10-4 

■ Taxonomy of Applications 10-4 

■ Starting an Application 10-4 

■ Killing an Application 10-6 



Table of Contents 



I 





Miscellaneous Topics 
ClassTarget 

ClassTarget is designed to allow application programmers to safely keep a refer- 
ence to one object inside another object. Target references are 'safe' in the sense 
that they look after all the associated NeWS reference counting issues. (See the 
Memory Management chapter in the XI 1 /NeWS reference manual for a full 
explanation of reference counting in the Xll/NeWS server.) 

You can instantiate ClassTarget directly, but applications will more commonly 
use this class as a mix-in. At present ClassTarget is mixed-in to ClassControl 
and ClassSelectionList, and hence its features can be used directly in any control 
or menu. 

The reason that controls and menus include ClassTarget is because they both 
have callback procedures in which application programmers specify the action 
that should take place when a button is pressed, a slider is dragged, a menu 
item is selected, and so on. Typically this action will consist of sending a mes- 
sage to some other object. It is the target mechanism that nmintains the refer- 
ence to this other object. 

Setting and Getting the Target 

Sending /settarget to an instance of some subclass of ClassTarget associates a 
target object with it. The /target method returns this object. The argument to 
/settarget can be any NeWS object, although it will typically be an instance of 
some class. If your target is not an instance (or a class), the /sendtarget method 
(see below) will cause a a typecheck error. 

It is not usually necessary to explicitly un-set a target. The act of destroying an 
object with a mixed-in target will automatically clear that target reference. A tar- 
get can however be manually cleared by calling the method /cleartarget. 

Methods: 

/settarget 

/cleartarget 

/target 
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Sending to the Target 

The target mechanism does not automatically dispatch your callback to some 
remote object. You must explicitly do this by calling /sendtaxget from within 
your callback. If the target is currently null /sendtarget will cause an error. 

Methods: 

/sendtarget 



Example 

The following example assumes that we want to create an OpenLookButton 
whose purpose is to print something in the footer of a frame (not necessarily the 
one containing the button) when the button is pressed. Assume that we already 
have a frame called /myframe: 

f \ 

/m^utton 

UCjQt lt*0 nulX $ -1 rpH 

iTriaiAelTUir^er /mu OpariXoolc&utton aabd 

myframd /aettarigat tnybutton aapd 

% Jnaort nQ^tton into some ox aiinpXy 
% activate it and map It Onto tha framabuffOr, aa in the 
% /demo method for OpenLookButton 





When mybutton is pressed the button itself will be put on the stack, and the 
callback executed. The '5 -1 roll' makes the button tf\e subject of the /sendtarget 
method, which in turn makes myframe the subject of the /setfooter method. 
Finally the left-hand footer is set to the string "Ck>t it!". 

Note that /settarget is called after the button is created, but before it is activated. 
If the button were activated before the call to /settarget there would a chance 
that the user could press it while the target was still null. This would cause an 
error. 
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Note finally that since the callback does not contain a direct reference to any 
particular frame, there is nothing to prevent the application from changing the 
button's target (via /settarget) at any time. This would cause the /setfooter mes- 
sage to be sent to some other object the next time the user pressed the button. 
Of course, this new target object should be some other frame (or should at least 
understand the /setfooter message). 

Automatic Menu Targets 

In recognition of the fact that the obvious target for a menu callback is the can- 
vas which received the MENU press and caused the menu to be shown, 
ClassCanvas includes code to automatically set the target for menus that it 
manages. 

By default (and unless the automatic menu targeting is defeated) every time a 
menu is brought up the canvas which received the MENU press sets itself to be 
the target of the menu before showing it. See the sections on Menus and 
ClassCanvas for a more detailed explanation of this behavior. 

Disappearing Targets 

Targets do not ensure the continued existence of the objects they reference. If 
the application removes its last hard reference to the targetted object, the target- 
ting mechanism will notice this and clear the (soft) target reference. Thus it is 
possible for a target to become null without having been explicitly cleared by 
the application. Robust applications which expect this behavior should not 
blindly use /sendtarget in their callbacks. They should first test whether there is 
still a target to send to. 

How Targets Work 

A target consits of two NeWs data structures: a soft reference to the remote 
object, and an interest in that object's obsolesence expressed in the global UI 
event manager. 

When no more hard references to the targetted object exist NeWS sends an 
/Obsolete event signalling that its useful life has come to an end, and all 
remaining references (the soft ones) should be cleared so that storage allocated 
for the object can be reclaimed. 
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This /Obsolete event is caught not only by the object itself (through the stan- 
dard mechanism in class Object), but also by the instance of QassTarget which 
is referencing it. On receipt of this event the QassTarget instance silently 
removes its reference to the targeted object, thus allowing it to be reclaimed. 



News Development Environment Applications 

Taxonomy of Applications 

tNt application programs fall into three natural categories, depending on their 
complexity: 

1 . PostScript-only applications. These are small programs, often demonstra- 
tion programs, that execute entirely in the server. The code to implement 
these programs is typically downloaded via psh(l), and is usually places 
in the userdict associated with the psh connection. 

2. PostScript / CPS applications. Any application with a client-side will use 
CPS, and those without asynchronous messages from the server to the 
client may not need to use the Wire Service. 

3. PostScript / CPS / Wire Service applications. This is the most general 
category, and will include most medium and large scale applications. 
These applications typically start by sending PostScript code to the server 
via CPS. They then enter the Wire Service's Notifier, which receives and 
distributes the user interface events that require client-side processing. 



Starting an Application 

See the Wire Service sections of this manual and the CPS section in the NeWS 
2.0 Programmer's Guide for details of starting an application with a client-side. 
What follows are the simple details of starting a PostScript-only application, or 
the PostScript-based component of a mixed client-server application. 

Below is a standard template for starting the PostScript component of an tNt 
application. It is explained below. 
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H I 

^ Definition of 'wyAppCwvw' » end other 
% i^aication-speclflc claeees. 

/frame 

[M/AppCanvas} [} fratneli^ffer /new OpenLookBaaeFrame send 

/activate frame send 
/place frame send 
/map frame send 






% These two lines are only present in PS~only applications. 

newprocessgroup 

currentfile closeflle 




Most applications start by placing a base frame on the screen. The client of this 
frame will be an instance of some application-specific class. 

It is important that a reference to this frame be maintained in some non- 
transient dictionary. Without this reference the frame and its contents would be 
reclaimed by the NeWS memory management system immediately. This is the 
reason for defining / frame in the userdict. 

Typical applications then activate the frame, by sending the /activate method to 
it. This has the effect of starting event management on the frame and every 
canvas within it. 

The next task is to establish a position and size for the application, /place per- 
forms this task. It consults the desktop manager for a position, obtains a size by 
sending the / preferredsize method to the frame. 

Next the frame is made visible by sending the /map method to it. After this 
point the application is running independently, and responding to user input. 

Finally, and only if the application is completely server-based and loaded via 
psh(l), the cliche "newprocessgroup currentfile closefile" should be executed. 
This has the effect of breaking the connection with the psh without killing the 
application. 
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Killing an Application 

PostScript-only applications that were launched in the above manner may be 
killed in two ways: 

■ By the user selecting "Destroy” from the frame's menu. Applications can 
defeat this destruction by overriding the frame's /destroyfromuser 
method. 

■ By the application removing the reference to its base frame in the userdict. 
This will cause all the resources consumed by the application to be 
reclaimed by the NeWS server. 

Applications with a client component can most simply kill themselves by break- 
ing their connection. The most obvious way to do this is to exit their UNIX pro- 
cess. 
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Introduction 

The following sections detail the programmer's interface to tNt. First, the Wire 
Service functions are described, then the method interface for selected classes on 
the server side of tNt. 

Note that for the server side, the reference is incomplete. Only the most com- 
monly used classes are described, and only selected methods are given for those 
classes. 



Wire Service 

The purpose of the NeWS Wire Service is to provide a server-client communi- 
cations package of sufficient generality to support diverse client applications 
and toolkits. 

The Wire Service is nearly independent of the PostScript language server com- 
ponents of tNt. It does not presume the existence of any particular class, and 
should work as well with Lite clients as those based on the new PostScript 
toolkit (with the exception of the synchronizatrion routines.) It is an extension 
to CPS. 

The components of the Wire Service are: 

■ a connection manager to handle multiple connections to one or more 
servers; 

■ "handle” allocation procedures, so that items on one side of the wire may 
be referred to from the other side; 

■ a lightweight notifier on the C-side so that asynchronous messages from 
the server(s) can be dispatched to client functions; 

■ and a synchronization package so that server-based code can make RPC- 
style calls across the wire. These four components are described below, 
after the error conventions and reporting facilities. 
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Error Handling 

Most Wire Service interface functions return a value which can be coerced to an 
integer and tested for a 0 return value. Many of them return a boolean: TRUE for 
sucess, FALSE for failure. 

int wina JBrxnp; 
wixe^Erxoz3tring <> ; 

dtuut 

V Z ^ J 

When an error has occurred, its type is available in the wire_Ermo global vari- 
able, and a descriptive string is pointed to by wire_ErrorString. Like its 
UNIX equivalent the error condition is not cleared immediately after an error. It 
remains set until the next error. The function wire_Perror prints the current 
error string to standard error, prefixed by the user-supplied string. 

Connection Management 

The first component of the wire Service is the connection management routines, 
which support multiple connections per server and multiple servers per applica- 
tion. 
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st«t t*Xkii>g to m mxyw: V 

wirBjPpon (36an^) 

ChlM? 

/* Stop tallcing to « Openoct oonnootlon */ 
hool^m 

wjf 

IM;tixn a pointer to tha paio input ^ilo pointer V 
PSPIUB ♦ 
l#lXci_PSinpUt(w) 
wixojtfixa vj 

/* P^UxA a pointed to the pslO output fila poifi^er */ 
PaPItB * 

¥lte_PSoatput <w) 






wire_Open takes an argument to specify the particular server to connect to. An 
argument of NULL will cause the the NEWSSERVER environment variable to be 
used. If there is no such environment variable, DISPLAY is used. If this also 
does not exist then the current host i s used with default port 2000. If the argu- 
ment is not NULL then it should be a hostname, a NEWSSERVER-style string, or 
a DISPLAY-style string. These formats are discussed in the Xll/NeWS docu- 
mentation. 

wire_Close is straight-forward. If the argument is wire_ALLWIRES, all of the 
connections will be closed. In this case, FALSE will be returned if there is an 
error with any of the connections. 

wire_PSinput and wire_PSoutput are accessor functions to the psio file 
pointers. These are needed if a program wishes to access the psio files. (More 
details may be found in the NcWS Programmer's Guide.) Note that the current 
implementation uses 2 file descriptors per connection. Thus, the number of 
available wires is determined by the number of available file descriptors in the 
system. This is highly implementation-specific and may be changed in the 
future. 
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wire_Set Current has the effect of moving the appropriate file pointers into 
the PostScript and PostScriptInput global variables. All libcps calls will 
thereafter use this connection, lite act of opening a wire does not set it to be the 
current wire. This must be done manually. 

wire_Current returns the current coimection. It is necessary because the 
Notifier (see below) may itself change the current connection, depending on 
where the next message has come from. Qients that do not want to reply down 
the same connection as their up-coming message will have to call 
wire_SetCurrent again before they write. 

wire_Valid returns TRUE if w is a valid wire, or FALSE if it is not. 
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Applications nwy associate client data with each coimection via the 
wire_SetData and wire_Data interfaces. The most common use of this will 
be to reestablish some per-cormection application context when processing a 
message from a particular connection. 

r \ 

/* finable ii <ioWiedtiob V 

/* DiaabX^ a <s<«»0ctl<« ♦/ 

/* Sea %^thdr a ootmoetlon ia enabled 
iDbdXaioi 

y 



wire_Di sable is used to remove a wire from the Notifier temporarily. Later, 
wire_Enable can be used to restore Notifer service to the wire. While a con- 
nection is disabled, the Notifier will not read any messages from it, and no func- 
tions will be called on its behalf. The purpose of this function is to allow a client 
to negotiate with one server, and guarantee that it won't be interrupted by mes- 
sages from another. When first opened, a cotmection is enabled. Disabling a 
wire only affects its input side; writes to a disabled wire will succeed. The func- 
tion wire_Enabled reports whether a particular coimection is currently 
enabled. 

wire_ALLWIRES may be passed as a paramater to wire_Disable and 
wire_Enable in order to disable/enable all of the wires in a single call. An 
error is reported if there is a problem with any one of the connections. 
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/* FiegiBtfN; ^vmationn to be^ cwXXed on 
eofmo<±ion xdttding «rror V 

wiir9^,^frx<dbXm («r, <teath, disease* unknoMitag) 

WiWiJIiW W 

if^id (’^ddsth) (h' 

void <*dl}wa3ei 0 ? 

void <«^mlcncMntag) ()/ 

/♦ oa«r function^ Jdmo*waX cowiocticw teoninaticn */ 

<*do«th> (w> 
wiwijfi*® w 

/* U90T funobion, oqunoction {ootOQQX oxror 

(^iaoaae): tw) . 
ifizojrixo 

/* 9aor function, unsag^i^^texed tag is found */ 

i||||i||||||||||||||||i^|iiiiii|iii|||;|ii|i||| 

(^itmknolfntag) (w) 
irlxe^izsa Mf 

bafauXt functions for wire pxobXema */ 
void wireJ^MtiiPofauXt 0 ; 
void wixoJt>isoas^)efauXt<); 
void wireJPhknownTagDef ault O ; 

/* £at a token and ekip to the next tag V 
boolean 

Ndre SkipEventa 

y 



Application ptx>grammers n\ay supply three functions that the notifier will call 
after particular abnormal events. If the connection is terminated, other than by a 
call to wire_Close,(*death) () is called. This user-supplied function should 
not attempt to close the offending wire. If the notifier finds a token at the head 
of an input queue that is not recogtuzable as a dispatching tag, (^disease) () 
is called, and the current connection is preset to the offending one. It is the 
responsibility of this function to consume the leading non-tag values from the 
stream. Finally, if the notifier finds a dispatching tag which has not been 
registered using wire_RegisterTag, (*unknowtag) () is called. A NULL 
argument to any of these three arguments to Problems will leave that function 
unchanged. 
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If wire_Problems is not called, the functions wire_DeathDe fault, 
wlre_DlseaseDefault and wire_UnknownTagDe fault are used. 
wire_DeathDefault prints a message to stderr, DlseaseDefault cleans up 
the queue and prints a message to stderr, and wire_UnknownTagDe fault eats 
the tag and any following arguments, also printing a message to stderr. 

If wire_Problems is called with wire_ALLWIRES as the first parameter, then 
the same set of callbacks will used for all connections. 

wire_SkipEvent consumes the initial token on the current wire and any 
remaining input upto, but not including the next tag. If there is no next tag on 
the current wire wire_SkipEvent will not block waiting for one. This func- 
tion is useful when writing disease and unknowntag functions. 

f " ^ 

boolean 

wite_ikiclfileiCandler<£ile« callhadc, data) 

file"" ♦file; 

void (♦calObaclc) <) ; 

caddrjt data; 

boolean 

witeJtemoveFileKandler (file) 

FIuT 

V J 



wire_AddFileHandler adds a file to the Notifier's list of files to check. When 
data is detected on the file, the callback is called and passed the data pointer. 
wire^RemoveFileHandler removes a file from the list. Note that the file is 
not a wire_Wire and cannot be enabled or disabled. There are no restrictions 
imposed on the file and it is up to the client to handle all operations within the 
callback. 

Note that these routines all take a file pointer. If a file descriptor is desired in 
the application program, a call to fdopen can be made with no adverse side- 
effects. 
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/♦ « ¥iw> to 9 . am»U integer ♦/ 

wiroJWlroTpIntiw) 

m 

/*. hb|> « 9nttll Int^cg^u: Into n wlcs */ 
wlxoJWlro 
wij?Oj:iltToWixe <i) 

V J 

Certain clients of the Wire Service may want to build data structures that are 
indexed by a wire. For this reason a pair of procedures (currently macros) are 
provided that nwp a wire into a uirique small integer and back again. This is 
meant to be used in those cases where client does not want to use the client 
data field associated with the connection. 

Handle Allocation and Registration 

Both the C and PostScript language components need to reference remote 
objects. The C progranuner may need to modify or queiy some PostScript 
language object he created earlier. Similarly, any PostScript language object 
which wishes to notify the client of a user event needs some way to specify the 
appropriate C function to invoke. Since references to PostScript language 
objects can not be f>assed across the wire, and C pointers can not easily be 
stored in the PostSaipt language world, we provide two "handle allocators" 
which generate and remember unique identifiers. 
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/« aMexvta « xjinge of nlimt tMgn */ 

iiiiiiiliiiiiiiiiiiiiiiiii 

1fi¥«_AlloQ«tOTa99 icount) 
iot oooot; 

/* Aa^igxi client 'tae^ tO an array of ac)dzo9oa9 V 
booXoan 

wlrtitjaiooatollttna^ (naiMa} 
char *naw 83 n? 

/* Mako tho tag allocator ign^ a xango of Intogm 
boolean 

ifirejI^Bdervea^a Ua£geat> 
int largest; 

V ■■ ■: : 

The Wire Service uses "tags", as provided by CPS, to drive its notifier. Before 
you can register a callback with the notifier, you must obtain a tag to associate 
with the callback. 

wire_AllocateTags takes a number N and returns another M, such that none 
of the integers M, M+1, ... M+N-1 are already allocated. These integers are han- 
dles whose primary use will be to dispatch messages from the server to client 
functions. 



wlre_AllocateNamedTags is a thin wrapper around wire_AllocateTags. 
It takes a NULL terminated array of pointers to integers, and assigns a tag 
through each of these pointers. Here is a typical use: 
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wire_ReserveTags is provided to allow dynamically-allocated tags to coexist 
with old-style constant tags. If you know that some piece of code uses tag 
values 1..50, then before calling AllocateTags you should call 
wire_ReserveTags (50) . This facility can also be used to leave space for your 
own private tag allocator if the one provided by the Wire Service doesn't meet 
your needs. Note: ReserveTags must be call^ before any coimections are 
opened. 



/* Register client handler ♦/ 
hoplean 

wlrejaegiaterTag<tag^ toxkcp, data) 
int tag; 

void (♦funcp) (> ; 

caddr^t data; 




/* The notifier will call your 

function in the following way V 

<*funcp> (tag, data) 
int tag; 

caddrjt data; 




/* Retrieve client function pointer */ 
void (*) 0 

wirejTagFunction (tag) 
int tag; 




Retrieve client data pointer 
caddrjt 

wireJTagData (tag) 
int tag; 





wire_RegisterTag allows you to associate a function pointer and a user data 
pointer with a tag. If this tag is ever found on the wire by the notifier, your 
function will be called. TagFunction and TagData retrieve the previously 
registered information. 

The Wire Service uses CPS usertoketxs as handles to PostScript language objects. 
These tokens are allocated on a per connection basis. The application is reponsi- 
ble for the registration of the usertoken in the server. These three calls are 
analogous to the above calls for tag allocation, except that they are done on a 
per-wire basis. Unlike wire_ReserveTags, wire_ReserveTokens is called 
after the connection has been opened. 
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f ^ 

« xmge ©Uent token on 
a specif Ic vlre 

iMilteJkllocatetdtena<ir« county 
ifize^ize w; 

int count; 

/* Assign tokens for a specific %ri?e to 
an atxay of addcesses 

l>ooiean 

ait«jaiocateliaMd9!o^^ ta^f^ant^) 
wixejHixe 

char ^natassU/ 

Make the token allocator a specific irire 
ignore a ra^e of integers */ 

boolean 

wizejReservetokens (w, largest} 

wire^ixe w; 

int largest; 

V J 

There is i\o equivalent to wire_RegisterTag () because this cannot be done 
from the C process - you need a reference to the PostScript language object to 
register it. Here is how you should use the usertoken facility for registering 
your server-side objects: 
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Notifier 

The purpose of the Notifier is to read tags from one or more server coimections, 
and depending on their value, call particular client functions. The functions that 
are called are those that were previously registered using RegisterTag () . The 
Wire Service provides both popular styles of notification: the notifier itself can 
handle the main loop, or else the client program can repeatedly request the 
dispatching of a single incoming message. The two styles can also be mixed in 
the same application. 




wire_Notify causes a single tag to be read from one of the active connections. 
(Round-robin scheduling is used when there is more than one connection with 
data ready for reading.) This tag is used as an index into the table of registered 
procedures. The procedure is then called with the handle and registered data as 
arguments. (See the function my_slider_handler in the example below). 
wire_Notify has the side-effect of setting the current connection, so that 
registered functions can read further arguments from the wire using normal 
CPS and psio functions. If there is no data available on any of the active connec- 
tions, wire_Notify will block until some message arrives or the period 
specified in the timeout parameter expires. If a timeout occurs or the block is 
interrupted by a system call, wire_Notify will return an error. 
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wire_WouldNotify does not block, and reports whether there are any pend- 
ing messages on the specified wire. The special argument, wire_ALLWlRES, 
causes this procedure to return TRUE if any of the active connections have input. 

wire_EnterNotif ier will be the main-loop for many client applications. It is 
reentrant, and can be intermixed with calls to wire_Notify. In fact, it will do 
little more than repeatedly call wire_Notify itself. A call to 
wire_EnterNotif ier will not return until the corresponding 
wire_ExitNotif ier has been executed. 

wire_ExitNotifier is called when the application programmer wants to exit 
from a (possibly nested) notifier loop. The corresponding 
wire_EnterNotif ier will return as soon as the registered procedure which 
called wire_ExitNotif ier itself returns. Pending messages are not processed 
in any way. 

Ease Of Use Macros 

The following macros are provided to enable data to be easily read from the 
current connection. It is assumed that the user of these macros knows the type 
of the data on the wire. Thus there is no type checking or error reporting. If the 
data is of the wrong type, garbage may be returned and the wire may be left in 
an undetermined state. The caveat to tf\is is that numeric arguments are con- 
verted by CPS (floating to integer and vice versa). 

f 

int <) 

i»t <) 

float wijnaJtoadGFloat <) 

* 

wireJReadString (str) 

<3har *atr; 

void wire GobbleAnyO 
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Synchronization 

CPS provides a mechanism for a client process to block pending notification 
from a server process. The wire service provides a complementary mechanism 
which will allow a server process to block pending notification from a client 
process. This will provide symmetric facilities for synchronous communications. 

The server interface looks like: 



proc /Wire Sync => — 



The proc is executed, and wire_Sync guarantees it wUl not return until the C 
client has acknowledged dealing with anything sent to it by the proc. Thus, for 
example, the PostScript program can ask the C program to send it some value, 
or to do some painting, etc., and be sure that C has responded to the request 
before tiying to do any more PostScript language code. Naturally, this makes 
some assumptions about the client; hence the requirement that the client be built 
on the Wire Service. 

The client interface is: 

r ^ 

/* Returns WOE i£ th^ is responding to 
s s;^nohronised request */ 

wire^In5ync(w) 
wire wire w; 

V ^ J 

wire_InSync simply checks to if the specified wire is responding to a syn- 
chronised request from the server, whid\ means that Post&ript language code 
sent now may be executed before PostScript language code sent earlier. This is 
a subtle but important point. 
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Constants 

The following constants are defined in the wire service: 




AbsoluteBag 

Subclass of ClassBag 
Source file: bagutils.ps 

This class can be directly instantiated 

An AbsoluteBag is a general purpose bag in which clients are given an absolute 
position when they are inserted. Regardless of the size and shape of the bag, 
clients always remain in this position thereafter. 

Direct Methods 

/addcllent name (null [x y client] /addclient 

name I null [x y client_class_args 
client_class] /addclient - 
There are several p>arameters required to add a 
client to an absolute bag: 

■ name, the client may be named or 
unnamed (null as the first argument). 
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/baggage 



/clientcount 



/clientlist 



/destroy 



/location 



/mlnslze 



■ baggage, which must be present in an 
absolute bag. It consists of the x and y 
coordinates at which the client will be 
located. 

■ client, which may be an instance or a class 
to instantiate, along the same lines as 
described in the section on ClassBag. 

In the example below, the bag makes an 
instance of OpenLookButton, and stores it in the 
bag with the client name supplied. 

/b1 [20 50 (Foo) {...} OpenLookButton] /addclient mybag send 

See the ClassBag section for details on the nam- 
ing and iitstantiation of bag clients. 

client /baggage [x y] 

Returns the baggage, which specifies the abso- 
lute position of the client in the bag. 

- /clientcount n 

Returns the number of clients currently in the 
bag. 

- /clientlist [clientl client2 ...] 

Returns an array of clients, with the canvas 
clients in the same order as they were inserted 
into the bag, unless explicitly changed by the 
application. 

- /destroy - 

Destroy the bag and its clients. Refer to the 
ClassBag /destroy method for the additional 
information on the use of this method. 

- /location x y 

Return the location of the origin of the bag rela- 
tive to the CTM. 

/minsize minwidth minheight 
Compute the minimum acceptable size for this 
bag. This is how big the bag must be to hold the 
clients at their current sizes (not their nrdnumum 
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/move 



/new 



/preferredsize 



/removeclient 



/reshape 



/sendclient 



/set baggage 



sizes). A well behaved application will respect 
this size when reshaping the bag in response to 
user mouse actions. 

X y /move - 

Move the origin of the bag to the specified loca- 
tion, in CTM coordinates. 

parent canvas /new instance 

Create an absolute bag parented to the specified 

canvas. 

- /preferredsize preferredwidth prefer- 
redheight 

Calculate the "ideal" size of the bag, which 
defaults to the minimum size. Well behaved 
applications will respect this size when initially 
displayed the bag. 

client I name | n /removeclient oldclient 
true 

client I name | n /removeclient false 
Remove the client given, named or indexed in 
the argument. The method returns true and the 
client object if the client is found, otherwise it 
returns false. 

X y w h /reshape - 

Reshape the bag to the dimensions given and 
invalidate it This results in the bag being layed 
out as the first step in painting it. 

<args> /method /name /sendclient results 
Send the specified method, with any arguments, 
to the named client. An error results if the 
client is not in the bag. 

client [x y] /setbaggage 

Set the client's positioning coordinates. 
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/settopdown 



/size 

/topdown? 



Class Variables 

/TopDown? 



see also: 

ClassBag 



bool /Mttopdown - 

Defiite the orientation of the bag's coordinate 
system as seen by clients: true sets the coordi- 
nates "top-down', false sets them "bottom-up". 
See the /topdown? method for more details. 

- /size w h 

Return the width and height of the bag in coor- 
dinates of the CTM. 

- /topdown? bool 

Return the positioning of the bag's coordinate 
system: true if the coordinates are "top-down', 
with (0,0) at the upper left comer of the bag. 
False means the coordiitates are "bottom-up", 
with (0,0) at the bottom left comer, which is the 
standard NeWS orientation. 

Note first, that this positioning effects the clients 
of the bag as well as the bag itself. If the bag's 
coordinates are "top-down" (origin at the upper 
left), then so is the origin of each client. 

Note second, that this variable only effects the 
orientation of clients inside the bag. Externally, 
as a News canvas, the bag's origin remains at 
the lower left comer, regardless of this variable. 



This boolean variable reflects the positioning of 
the bag's coordinate ^stem: tme if the coordi- 
nates are "top-down', false if the coordinates 
are "bottom-up". See the /topdown? method 
for more details. 
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ClassBag 

Subclass of ClassCanvas 
Source file: bag.ps 

This class should be subclassed rather than directly instantiated. 

A bag is a type of canvas that manages a group of clients, either canvases or 
graphics. Bags formalize the concept of containment. 

When a client canvas is added to a bag, it is reparented to the bag, becoming a 
child of the bag in the NeWS canvas tree. Thus, in most applications, the inte- 
rior canvases descended from the application's base frame are typically bags. 

A bag provides its clients with names, shared event management, and collective 
layout and damage repair. 

Direct Methods 

/activate - /activate 

Activate event management for the bag and all 
its canvas clients. This method is call^ recur- 
sively on clients that are themselves bags. 

/addcllent name | null [... client] /addclient 

name I null [... clientclass] /addclient - 

name I null client /addclient - 

There are several ways to add a client to a bag. 

The client can be specified as an instance of a 
subclass of either OassCanvas or ClassGraphic. 
Or the client can be specified by a subclass of 
ClassCanvas, in which case, the bag will instan- 
tiate the class and accept that instance as its 
client If arguments are required to instantiate 
the class, they must be supplied along with the 
"baggage" described below. Note that a parent 
argument is not required when specifying a 
class to instantiate: the bag will be the parent. 
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/addfocusdescendant 



The client may be named or uimamed. The 
name may be any legal dictionary key in the 
PostScript language. If a name is given, the 
client can later be accessed by supplying that 
name to the /getbyname method. If null is 
given as the name, the client is accessed by the 
order in which it was put into the bag, the first 
client being number 0. 

The application must remember the insertion 
order of unnamed clients. The bag will return a 
client given its index, but there is no method for 
which the bag returns the index. 

The client can be accompanied by "baggage", 
which is data bundled into an array with the 
client instance (or class). This information is 
used by bag subclasses, typically in laying out 
the clients. The arguments necessary to instan- 
tiate a client from a class are suppli^ next to 
the baggage, but are not consumed during 
instantiation and are not stored. 

Note that if you move a client from one bag to 
another, you must first send /removeclient to 
the bag fi\e client is leaving before sending 
/addclient to the bag the client is entering. 

For examples of adding a client to a bag, see the 
introductory section. Bags. 

client /addfocusdescendant - 
This method is used to notify all parent bags of 
this bag that they have a new descendant that is 
interested in input focus. This can happen 
either because a new key consumer was added 
to this bag or because an existing client changed 
status, becoming interested. 

The method is called automatically when adding 
a client to a bag. It is not generally necessary to 
override this method, either. 
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/addkey consumer 



/baggage 



/client? 



/clientcount 



/clientlist 



/deactivate 



/destroy 



client /addkeyconsumer - 
This method is called automatically when 
adding to the bag a client that is interested in 
keyboard input (a key consumer). 

client /baggage [data] 

Returns the baggage data that was passed in 
when client was added to the bag. 

/name /client? boolean 

Returns true if name belongs to an existing client 

in the bag. 

- /clientcount n 

Returns the number of clients currently in the 
bag. 

- /clientlist [clientl cllent2 ...] 

Returns an array of clients, with the canvas 
clients in the sante order as they were inserted 
into the bag, unless explicitly changed by the 
application. 

- /deactivate - 

Turn off event management for the bag and all 
clients. This renr»oves all interests expressed by 
the bag and clients. It also kills the event 
manager process if it is owned by the bag, oth- 
erwise it notifies the event manager that the bag 
is no longer active. 

- /destroy - 

Destroy the bag and its clients; send /destroy- 
dependent to each client and remove any associ- 
ated baggage. This method is called automati- 
cally when the NeWS memory reference count 
on the bag goes to zero. 

Any clients remaining after sending /destroy- 
dependent are reparented to an offscreen can- 
vas. This allows a subclasser to override /des- 
troydependent for any client that should not be 
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/destroydependent 



/focustarget 



/foreachclient 



/getbyname 



/graphicclientcount 



/graphicclientlist 



/?invalidate 



destroyed as the result of destroying the bag 
and oAer clients. 

- /destroydependent - 

This method is sent to each client of a bag when 
the bag is destroyed. By default, it does /des- 
troy self send. Override this method for any 
client that should not be destroyed at the same 
time as the bag and other clients. 

- /focustarget canvas I null 

Return the current input focus target for the 
bag, or null if there is none. The focus target for 
a bag is the client canvas to which the bag will 
forward input focus when the bag receives it. 

proc /foreachclient 

Call the given procedure for each client in the 
bag, with the client on the top of the operand 
stack. 

name /getbyname client true 

name /getbyname false 

Return the client named by the argument and 

true if the client exists in Ae bag. Otherwise 

return false. 

Note that the name may be an integer if the 
client was entered without a name. 

- /graphicclientcoimt n 

Return the number of graphic clients in the bag. 
The total number of clients (/clientcount) tninus 
this number equals the number of canvas clients. 

- /graphicclientlist [cl lent 1 client2 . . . ] 
Return an array of graphic clients of the bag, or 
the nullarray if there are none. To get an array 
of canvas clients, use /children+. 

methodname /Tinvalidate - 
This method is used to control which methods 
invalidate the bag; a naethod will call /?invali- 
date with its own name as the argiunent and 



11-22 



tNt Technical Reference Manual 




Interface Reference 



/invalidate 



/last focustime 



/layout 



/location 



/minsize 



/?invalidate will decide whether to invalidate 
the bag. By default the following methods call 
/?invalidate: /addclient, /removeclient, /reshape. 
Override this method if you want a bag not to 
invalidate automatically after one of those 
methods listed above. 

- /invalidate 

This method is called by the toolkit (through 
/?invalidate) to mark the bag invalid, meaning 
that its layout is out of date. The application 
does not normally call this method directly, but 
instead it is indirectly invoked by /addclient, 
/removeclient, /reshape. 

- /lastfocustime time 

Return the time when the bag last had the input 
focus. 

- Aayout - 

Perform layout on all clients of the bag to move 
and/or reshape them based on the current size 
and shape of the bag. Note that this method is 
not usu^ly directly called by an application, but 
is invoked indirectly by /addclient, /remo- 
veclient, /reshape. 

- /location x y 

Return the location of the bag's origin in CTM 
coordinates. 

/minsize minwidth minheight 
Compute the minimum acceptable size for this 
bag. A well behaved application will respect 
this size when reshaping the bag in response to 
user mouse actions. 

When subclassing, override this method if the 
calculations do not require the current canvas to 
be the bag. (If the calculations do require the 
bag as the current canvas, override /MinSize 
instead.) 
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/move X y /move 

Place the origin of the bag at the point (x,y) in 
the coordinates of the CTM. 

parentcanvas /new instance 
Create a bag parented to the specified canvas. 

- /newinit - 

Override this method to initialize a bag with 
arguments supplied to /new. The overridden 
/newinit should use the arguments in its initiali- 
zation and consume them (remove them from 
the stack). 

/preferredsize - /prefeiredsize preferredwidth prefer- 

redheight 

Calculate the "ideal" size of the bag. Well 
behaved applications will respect this size when 
initially displayed the bag. 

When subclassing, override this method if the 
calculations do not require the bag to be the 
current canvas. (If the calculations do require the 
bag as the current canvas, override /Preferred- 
Size instead.) 

/reraoveclient client | name I n /removeclient oldclient 

true 

client I name | n /removeclient false 
Remove the client given, named or indexed in 
the argument. The method returns true and the 
client object if the client is found, otherwise it 
returns false. The effect is to remove the client 
and any of its baggage, reparent the client to an 
offscreen canvas, and deactivate it if it was using 
the bag's event manager. If the client was 
activated before being added to the bag (had its 
own event manager) it remains active. 

/removefocusdescendant client /removefocusdescendant 

This method is sent to notify a bag that a des- 
cendant (canvas) client has stopped being 
interested in input focus. If that descendant was 



/new 

/newinit 
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/ removekey consume r 



/reshape 



/sendclient 



/set baggage 



/setfocustarget 



/size 



/valid? 



the focus target, this method calls /MakeFocus- 
Target to obtain a new focus target. This 
method is used a bag (/removekeyconsumer) to 
notify any parent bags when a child stops con- 
suming keys. 

client /removekeyconsumer - 
Notify parent bags that a child of this bag has 
stopped being a key consumer. This can happen 
either because the child was removed from the 
bag, or remained in the bag but revoked its 
interests in keyboard focus events. This method 
is not directly called by an application, but is 
invoked through /removeclient. 

X y w h /reshape - 

Reshape the bag to the dimensions given and 
invalidate it. This results in the bag being layed 
out as the first step in painting it. 

<args> /method /name /sendclient results 
Send the given method with arguments to the 
named client. 

client [attributes] /setbaggage 
Store the extra information ("baggage”) for the 
client. Typically in bags this information is used 
in layout. 

clientcanvas | null /setfocustarget - 
The argument is stored in the /FocusTarget vari- 
able. If it is null, the bag will cease to be 
interested in input focus. Otherwise, the client 
canvas named in the argument becomes the 
focus target for the bag. 

- /size w h 

Return the current size of the bag in the coordi- 
nates of the CTM. 

- /valid? boolean 

Return true if the bag's layout is valid. 
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/? validate 
/validate 

Subclass Methods 

/BagBegin 

/BagEnd 

/CheapIntegerClient 

/CheapIntegerName? 

/DeRegisterByNanie 

/DeRegisterByOrder 



- /?validate - 

Validate if the bag's layout is currently invalid. 

- /validate ~ 

Lay out the bag in preparation for painting. 

This method is not generally called explicitly by 
an application, but rather gets invoked through 
/paint or /fix. 



- /BagBegin 

Set the bag as the current canvas and save the 
current NeWS graphic context, establishing a 
"bag context”. This allows layout procedures to 
operate in the CTM of the bag. 

- /BagEnd 

Restore the previous NeWS graphics context. 

int /CheapIntegeiClient client 
Return the client corresponding to the array 
index given as an argument. 

int /CheapIntegerName? boolean 
Returns true if the argument is an integer and 
clients are stored by number in an array. 

/name /DeRegisterByName oldclient true 

/name /DeRegisterByName false 

Remove the named client from the bag. Return 
the named client and true if the client is in the 
bag, otherwise, return false. 

client I int /DeRegisterByOrder client true 
client I int /DeRegisterByOrder false 
Remove the client indicated by the argument, 
either the client object itself or its index in the 
internal client array. The method returns the 
client object and true if it was present, otherwise 
false. 
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/DeRegisterClient 



/FixChildren 



/Layout 



/MakeFocusTarget 



/MlnSize 



/NewClient 



/name | client /DeRegjsteiClient oldclient 

true 

/name | client /DeRegisteiClient false 

Remove a client, whether stored by name or by 
order of insertion. 

- /FixChildren - 

This method sends /fix to each canvas, not 
graphic, client of the bag 

- /Layout 

Override this method to perform specific layout 
functions for a subclass, such as placement and 
sizing relative to the bag. When this method is 
called by /layout, the bag will be the current 
canvas, so the subclass can use information 
about the bag's size and coordinates. 

newcanvas | null /MakeFocusTarget 
newcanvas' | null 

Override this method to decide which client 
should receive the input focus. This method is 
called when adding a key consumer to a bag 
that has no focus target or when removing the 
current focus target. 

- /MinSize w h 

This method is called by /minsize with the bag 
as the current canvas to calculate the minimum 
size for the bag. Override it to implement spe- 
cial calculations for a subclass, for example bas- 
ing the minimum size of the bag on the 
minimum sizes of clients. 

parentcanvas /NewClient instance 
This method is used when creating a bag client 
from a dientclass given as an argument to 
/addclient It is executed in the context of the 
class being instantiated. Override this method 
to provide special treatment of a newly created 
client instance. 
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/NoticeDescendantFocus event /NoticeDescendantFocus - 

This method is called by /NoticeFocus when the 
input focus has moved into a child of the bag; it 
sets the focus target variable (/FocusTarget) to 
the child canvas. 



/NoticeFocus 



/NoticeFocusEnterExit 



/NoticeSelf Focus 



/PaintChildren 



/PaintGraphicChildren 



/PreferredSize 



event /NoticeFocus - 
This method is the callback from the interest 
expressed by the bag in noticing input focus 
changes; it is called when input focus enters a 
focus-forwarding bag or any of its children. It 
determines the focus target and transfers the 
focus to it via /TransferFocus. If the focus 
changes on the bag itself, /NoticeSelfFocus is 
called. If the focus changes on a client of the 
bag, /NoticeDescendantFocus is called. 

event /NoticeFocusEnterExit - 
This method is called when focus enters or 
leaves a bag hierarchy; not when focus shifts 
from one client to another client of a bag. Over- 
ride it when special behavior is required on 
gaining or losing input focus. 

event /NoticeSelfFocus - 
This method is called when focus moves into or 
out of a bag. It transfers the focus to the client 
canvas indicated by /FocusTarget. 

- /PaintChildren - 

This method is called by /paint to paint each 
canvas client of the bag. 

- /PaintGraphicChildren - 

This method is called by /paint to paint each 
graphic client of the bag. 

/PreferredSize w h 

This method is called by /preferredsize with the 
bag as the current canvas. By default it returns 
/minsize. Override it to perform any special cal- 
culations for a subclass, for example, considering 
the preferred sizes of clients. 
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/ Regi s t e r ByName 



/RegisterByOrder 



/RegisterClient 



/TransferFocus 



/name client /RegisterByName - 

This method adds a client to the bag by name. 

client /RegisterByOider - 

This method adds a client to the bag by the 

order of insertion. 

/name I null client /RegisterClient 
This method adds a client to the bag by name or 
by the order of insertion, depending on the 
argument given. 

canvas /TransferFocus ~ 

Transfer input focus to the client indicated by 
the /FocusTarget variable. 



Class Variables 

/FocusForwarder? 



/FocusNoticer? 



/FocusTarget 



see also: 

ClassCanvas 



This variable reflects the bag's interest in input 
focus on behalf of its clients. When true, this 
variable indicates that the bag will receive input 
focus and then pass it on ("forwward" it) to the 
client indicated by /FocusTarget 

This variable is true when the bag is interested 
in being notified whenever input focus enters or 
leaves it or any of its descendants. 

The client stored in this variable receives the 
input focus if the /FocusForwarder? variable is 
true. 
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ClassBaseFrame 

Subclass of ClassFrame 
Source file: frame.ps 

This class should be subclassed rather than directly Instantiated. 

This class is not for direct use; rather it supports frame (window) subclasses, 
such as the OPEN LCXDK window frames. If you need a simple window frame 
for inunediate use, consider one of the OPEN LOOK frames: 

■ OpenLookBaseFrame 

■ OpenLookPropertyFrame 

■ OpenLookNoticeFrame 

■ OpenLookCommandFrame 

■ OpenLookHelpFrame 

ClassButton 

Subclass of ClassControl 
Source file: button.ps 

This class should be subclassed rather than directly Instantiated. 

This class is the superclass for OpenLookButton as well as various pins and 
anchor boxes used throughout the toolkit. The following methods should be stu- 
died in conjuction with ClassControl. 

Direct Methods 

/graphic - /graphic obj 

Return the graphic object of the button. 

/set graphic thing {graphic /setgraphic 

Convert the argument to a graphic, if necessary, 
and store it as the button's graphic. Then, 
invalidate the button to require layout before 
repainting. 
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Subclass Methods 

/CreateGraphic 



/EnGraphic 



/UnGraphic 



see also: 

ClassControl 



thing /CreateGraphic graphic 
This method is SubClassResponsibility. 

Override it to create a graphic from the thing 
supplied. 

thing I graphic /EnGraphic graphic 
Return a graphic corresponding to the argument 
supplied. If the argument is a terminal graphic, 
return it as is. Otherwise, use /CreateGraphic 
to make it into a graphic. 

graphic /UnGraphic thing I graphic 
Return the thing or graphic that was supplied to 
construct this graphic. If the object is already a 
terminal graphic, return it as is. 



ClassCanvas 

Subclass of Object 
Source file: canvas.ps 

This class can be directly instantiated, but is usually subclassed. 

ClassCanvas provides the structure underneath most of what you see on the 
screen (the "look" of the toolkit), as well as linking it to input (the "feel" of the 
toolkit). A tNt canvas is basically a NeWS canvas with additional structure to 
support object oriented programming, display of the canvas, event management, 
and NeWS canvas tree operations. 
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Direct Methods 

/activate 



/active? 



/ autotargetmenu 



/autotargetraenu? 



/bbox 



/bboxfromuser 



/callhelp 



/canvas 



- /activate - 

Activate event management for this canvas; 
express the interests returned by the /makein- 
teiests method. Create an event manager for 
the canvas if one cannot be found in one of its 
parent canvases. 

- /active? bool 

Return true if event managenrtent has been 
activated on the canvas. 

bool /autotargetmenu - 
When true (the default), the canvas is automati- 
cally made the target for its associated menu 
whenever the menu is popped up. 

- /autotargetmenu? bool 

Return true if the canvas is automatically the 
target of its associated menu when the menu is 
popped up 

- /bbox X y w h 

Return a bounding box for the canvas computed 
by the NeWS getbbox operator. 

- /bboxfromuser x y w h 

Return a bounding box determined by mouse 
movement from the user. This method causes 
the cursor on the screen to change to a crosshair, 
and the NeWS process to block waiting for the 
user to press down the SELECT button. The 
user presses and drags out a rectangle that 
becomes the bounding box when the button is 
released. 

- /callhelp 

Call the help procedure for this canvas. 

- /canvas canvas 

This method returns the NeWS canvas object 
associated with this tNt canvas instance. 
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/children+ 



/children- 



/deactivate 



/descendants 



/destroy 



/eventragr 



/farthest corner 



- /childien+ array 

Return an array of NeWS canvases, the children 
of this canvas in the NeWS canvas tree. The 
array is ordered from the bottom canvas first to 
the top canvas last 

- /children- array 

Return an array of NeWS canvases, the children 
of this canvas in the NeWS canvas tree. The 
array is ordered top canvas first to bottom can- 
vas last. 

- /deactivate 

Turn off event management for this canvas. If 
the canvas's event manager is shared with 
another canvas, notify the event manager to 
/deactivatecanvas for this canvas. If the event 
manager is owned by this canvas, destroy it. 

- /descendants array 

Return an array of canvases, the descendants (if 
any) of this canvas. The array is ordered by 
proximity to this canvas, children before 
grandchildren. Within each generation, top can- 
vases come before bottom canvases. 

- /destroy - 

Destroy this canvas, have it removed from the 
canvas tree and interest lists. Before the NeWS 
server can reclaim the memory used by the can- 
vas, all references to it must be remove. When 
subclassing, override this method to make sure 
any additional references you have made to an 
instance of the subclass are removed. 

- /eventmgr eventmgr 

Return the event manager process for this can- 
vas. 

X y /faithestcomer x' y' 

Return the comer of the canvas farthest from the 
given point, in the coordinates of the CTM. 
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/fix 



/getcolors 



/help 



/invalidate 



/isinside? 



/keyconsumer? 



/last focustime 



/location 



/lockminsize 



- /fix - 

Called by the damage handler to repaint only 
the damaged area of a canvas using /FixCanvas. 
To paint the entire canvas use /paint 

- /getcolors strokecolor fillcolor 
textcolor 

Return the three colors of a canvas, used for 
stroking its outline, filling the interior, and text. 
By default these colors are those of the parent 
canvas. 

- /help proc | null 

Return the canvas's help procedure (as set by 
/sethelp), or null if there is none. 

- /invalidate - 

Mark the canvas "invalid”, the interpretation of 
which is left to subclasses. In the case of bags, 
for example, invalid means that the bag's layout 
is out of date. 

xO yO xl yl /isinside? bool 
Return true if the canvas is inside the box 
specified by its lower left and upper right 
comers respectively. 

- /keyconsumei? bool 

Return true if the canvas is interested in input 
focus, 

- /lastfocustime time 

Return the last time the input focus was on this 
canvas. 

- /location x y 

Return the location of the origin of the canvas 
relative to the CTM. 

null I w h /lockminsize 
Change the minimum size (/minsize) for this 
canvas instance. If the argument is null, restore 
the default value for the class. 



11-34 



tNt Technical Reference Manual 




Interface Reference 



/makeinterests 



/map 



/mapped? 



/menu 



/methodancestors 



/minsize 



- /makeinterests array 

Return an array containing the interests of this 
canvas, using the /Makeinterests method. In 
normal use, this method is nor directly called by 
an application. 

- /map - 

Set the /Mapped attribute of the canvas. Refer 
to the News 2.0 Programmer’s Guide for the 
model of how this affects the canvas becoming 
visible on the screen. 

- /mapped? bool 

Return true if the canvas is currently mapped 
onto the screen. 

- /menu menu I null 

Return the menu object associated with this can- 
vas as set by /setmenu and stored in the /Can- 
vasMenu variable The menu is displayed when- 
ever the MENU button is pressed with the 
pointer over the canvas. Return null if there is 
no menu set. 

method /methodancestors array 
Return an array of the ancestors in the NeWS 
canvas tree that recognize the method supplied 
as an argument. If the class to which the 
method is sent recognizes the method, it is 
included in the array. If the sender of this 
method does not want the immediate recipient 
of the method included, it should send the 
method to the parent. 

- /minsize w h 

Return the minimum size for this canvas as 
specified by the subclass of ClassCanvas to 
which it belongs. This value is used by the util- 
ity functions /reshapefromuser and 
/stretchcorner, which will not allow any user 
mouse action to make the canvas smaller than 
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/move 



/ move f jTcmuSeiT 



/new 



/newinit 



/paint 



/parent 



/parentdescendant 



/minsize, the sniallest that the user can make the 
canvas with the mouse. 

X y /move - 

Move the origin of the canvas to the spedfied 
location in the coordinates of the CTM. 

- /movefromuser - 

Interactively move the canvas. This method 
uses a class variable /DragFrame? to control 
whether or not a wire frame or the canvas itself 
is shown as the canvas is moved. 

parentcanvaa /new Instance 
Return a new canvas instance, with the specified 
canvas as its parent. The parentcanvas argu- 
ment is consumed by /newobject 

args | - /newinit 

This method is called by /new to initialize an 
instance. It is overridden to allow subclassers to 
perform any specific initialization on the 
instance. \^en it is overridden, the method 
should first do /newinit super send so that the 
superclass can do its initialization. Then it 
should do any specific inititalization the class 
requires and consume the arguments on the 
stack. 

- /paint 

Paint the entire canvas, using the /PaintCanvas 
method. 

- /parent Instance 

Return the NeWS canvas that is this canvas's 
parent in the canvas tree. 

canvasl /parentdescendant canvas2 true 

canvasl /parentdescendant false 

Note that this method is sent to a class, not an 
instance. 

This method asks a class to return the canvas 
closest to the given canvas in the NeWs canvas 
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/parents 



/path 



/place 



/preferredsize 



/reparent 



tree that is also an instance of a subclass of that 
class. (Basically, it asks a class "which is the 
canvas closest to me that is also a descendant of 
you?") For example, 

mycanvas /parentdescendant ClassFrame send 
returns the frame surrounding mycarwas and 
true. If there is no such canvas, the method 
returns only false. 

- /parents array 

Return an array of the canvas's ancestors 
ordered from its (immediate) parent first to 
framebuffer last. 

X y w h /path - 

Using the arguments to define a bounding box, 
this method returns a path that is the shape of 
the canvas sized to fit the box. You should 
override this method for any subclass that is not 
rectangular in shape. 

- /place - 

This method is overridden by subclasses that 
have a default placement scheme. For example, 
frames override this method to specify their 
default placement on the framebuffer. OPEN 
LCX)K frames override it to do staggered layout. 
The default action is to reshape the canvas from 
user input (/reshapefromuser). 

- /preferredsize width height 

This method allows a subclasser to specify the 
size a canvas should be when it is started. (For 
example, the /place method in frames calls /pre- 
ferredsize on its client canvas.) By default, this 
method simply calls /minsize. You should over- 
ride this method (or /PreferredSize) to specify 
the 'ideal' size for a canvas subclass. 

newparentcanvas /reparent - 

Move the canvas in the NeWS canvas tree, to 

have the given canvas as its parent. 
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/reshape 



/reshapefromuser 



/scroll 



/setcolors 



/setcursor 



Note: do i\ot call this method when using bags; 
they handle reparenting themselves. 

X y w h /reshape 

Reshape the canvas to fit the bounding box 
specified by the arguments, in the coordinates of 
the CTM. This method allovs^ the toolkit or the 
application to position the canvas on its parent. 

- /reshapefromuser 

Rediape the canvas fi’om user interaction. First, 
an application sends this method to a canvas. 
Next, the cursor on the canvas changes to a 
crosshair, and the application's NeWS process 
blocks until the user performs a press-drag- 
release with the SELECT button. Then, the can- 
vas is then resized to fit the resulting bounding 
box. but no smaller than the minimum size 
(/minsize). 

dx dy /scroll 

Scroll the contents of the canvas by the given 
increments. Non-retained canvases should over- 
ride /PaintScrolledAiea to update the canvas. 

strokecolor fillcolor 

textcolor /setcolors - 

Sets the colors for stroking the border of the 

canvas, filling its interior, and drawing text. 

Null as an argunaent means do not change that 
value. 

Intlkwd int|kwd|null /setcursor - 
cursorobject /setcursor 
The arguments to this method are either a 
NeWS cursor object or the parameters to iden- 
tify one in a special dictionary (/Cursors). These 
are the image and the mask identifiers, respec- 
tively. They can be either a keyword such as 
ptr or an integer. A null second argument 
means that the mask is the next item in the 
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/seteventmgr 

/sethelp 

/setkeyconsumer 

/ set last f ocust ime 
/setmenu 

/setpaintproc 
/set text font 



Interface Reference 



dictionary following the image specified in the 
argument. 

eventmgr | null /seteventmgr 
Make the argument the event manager for this 
canvas. If the argument is null, there will be no 
event manager. Normally an application does 
not call this method to set its event manager, 
using /activate to do it implicitly. 

proc I null /sethelp - 

Install or remove the canvas's help procedure. 

bool /setkeyconsumer 
This method stores its value as a variable to 
indicate whether the canvas will respond to 
input focus. True means interested in input 
focus. Simple applications using /QassKeysIn- 
terest do not need to call this method. 

time /setlastfocustime 

Promotes a variable to store the time when the 
input focus was last in this canvas. Simple appli- 
cations do not need to use this method. 

menu I null /setmenu 

Install or remove a popup menu for this canvas. 
The menu is activated by the user pressing the 
MENU button when the pointer is over the can- 
vas. 

proc /setpaintproc - 

This method redefines the painting procedure of 
a canvas (/PaintCanvas). 

font /settextfont - 

Set the text font object for a subclass or an 
instance. Note that because the font itself is 
stored, it may not agree with the font parame- 
ters specified by /settextparams. If there is a 
difference, the font takes precedence over the 
parameters. 
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/ s e 1 1 ext pa rams 



/settransparent 



/siblings+ 



/siblings- 



/siblingsabove 



/siblingsbelow 



/size 



/ St ret chcor ne r 



family pointsize encoding /settextparams 
Stores the parameters defining the text font for 
the canvas. 

bool /settransparent 

Set the transparency for the canvas (the /Tran- 
sparent key). If false, the canvas is made opaque 
and an interest in /Damage is automatically 
expressed 

- /siblings+ array 

Return an array of NeWS canvases with the 
same parent as this canvas, including this can- 
vas. The array is ordered by how the canvases 
(would) appear on the screen bottom first to top 
last. 

- /siblings- array 

Return an array of NeWS canvases with the 
same parent as this canvas, including this can- 
vas. The array is ordered by how the canvases 
(would) appear on the screen top first to bottom 
last. 

- /siblingsabove array 

Return an array of NeWS canvases on top of 
this one in the canvas tree, from the canvas 
immediately above to the one on top. 

- /siblingsbelow array 

Return an array of NeWS canvases below this 
one in the canvas tree, from the canvas immedi- 
ately below to the one on the bottom. 

- /size w h 

Return the width and height of the canvas in 
CTM. 

X y /stretchcomer - 
event /stretchcomer 

Reshape the canvas from user interaction with 
the farthest comer fixed, subject to minimum 
size constraints. If an event is supplied, its 
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/text font 

/textparams 

/tobottom 

/totop 

/transparent? 

/unmap 

/valid? 

/? validate 
/validate 



position is used to determine where the user 
began the interaction by pressing a button. Oth- 
erwise, the coordinates are supplied directly. 

- /textfont font 

Return the text font of the canvas. 

- /textparams family pointsize encoding 
Return the text font parameters of the canvas. 

- /tobottom 

Move the canvas to the bottom of its sibling list 
using the canvastobottom NeWS operator. 

- /totop - 

Move the canvas to the bottom of its sibling list 
using the canvastotop NeWS operator. 

- /transparent? bool 

Return the transparency of the canvas, true if 
transparent, false if opaque. 

- /unmap - 
Unmap the canvas. 

- /valid? bool 

Return true if the canvas is marked valid. 

- /?validate 

Validate the canvas if it is currently invalid. 

- /validate 

Mark the canvas as valid. QassCanvas does not 
itself interpret what validity means, but leaves it 
to subclasses to do so by overriding the indi- 
cated methods. For example, to a bag valid 
means not requiring layout at the moment. 
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Subclass Methods 

/BulldCanvasSend 



/Canvas 

/CreateEventMgr 



/Damage Int e re St 
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name | array /BuildCanvasSend proc 
This ntethod builds a callback for use with an 
interest in an event on this canvas. When a suit- 
able event occurs and matches the interest the 
callback will send a message to this canvas. 

That message is the name of a method or an 
array (executable or not) that was given as the 
argument to BuildCanvasSend. 

The callback is constructed so that it can identify 
this canvas from information in the event: the 
/Interest key of the event contains the interest, 
whose /Canvas key contains this canvas. The 
callback finds this canvas and sends the method 
name or array to it, making the array executable 
if necessary. 

For example: 

MenuButton /MenuNotify BuildCanvasSend 
/DownTransition Canvas eventmgrinterest 

PointButton {pop /OpenFrame} BuildCanvasSend 
/DownTransition Canvas eventmgrinterest 

application programmers will usually invoke 
/BuildCanvasSend indirectly through the 
simpler /Makeinterest method. 

- /Canvas canvas 

Return the NeWS canvas associated with this 
instance. 

- /CreateEventMgr emgr 

Create an event manager for this canvas. This 
method is automatically called by /activate if the 
canvas did not inherit an event manager from its 
parent. 

- /Damagelnterest Interest 

Return the canvas's stored damage interest. 
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/Descendant sRecurse 



/DisabledColor 



/EventMgr 

/FillCanvas 

/FillCanvasInterior 

/FillColor 

/FilterNonInstances 



/FixCanvas 



can /DescendantsRecurse can canO canl 
can2 . . . 

Return an array of canvases, the descendants (if 
any) of this canvas. The array is ordered by 
proximity to this canvas, children before 
grandchildren. Within each generation, top can- 
vases come before bottom canvases. This 
method is used by /descendants. 

- /DisabledColor color 

Return the color used if the canvas is "disabled”, 
the interpretation of which is left to subclasses. 
This me^od is a convenience to subclasses such 
as controls that have enabled and disabled 
states. 

- /EventMgr eventmgr 

Return the event manager for this canvas. 

color /FillCanvas - 

Fill the entire canvas using color. 

color inset /FillCanvasInterior ~ 

Fill the inside of the canvas using color. Leave an 
unpainted edge inset wide in canvas coordinates. 

- /FillColor color 

Return the fill color of the canvas. 

array /FilterNonInstances array' 

This method removes NeWS canvases that are 
not tNt canvases, ("non-instances") from arrays 
returned by methods that list canvases such as 
/children+, /children-, /siblings+, /siblings-, 
/siblingsabove, /siblingsbelow, /descendants, 
/parents. 

- /FixCanvas 

This is the method that handles the repainting of 
damaged portions of a canvas. It should be 
overridden in those subclasses that are able to 
efficiently repaint a damaged area rather than 
the entire canvas. 
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/GetCursorEncoding 

/HandleFix 



/HandleHelp 



/HandleMenu 



/Helpinterest 



/Make Interest 



/Makeinterests 



/GetCursorEncoding 

event /HandleFix - 

This is the callback for the damage interest 

(/Damageinterest). 

event /HandleHelp - 
This is the callback for the help interest (/Hel- 
pinterest). 

event /HandleMenu - 

This is the callback for the menu interest 

(/Menuinterest). 

- /Helpinterest interest 
Return the help interest object. 

name callback action canvas /Makeinterest 
interest 

This method is used when overriding /Makein- 
terests to create a single interest that includes 
the callback argument as an executable match on 
the /Action field. The name, canvas and action 
arguments are the values placed in the /Name, 
/Canvas and /Action keys of the interest, respec- 
tively. The canvas argument is usually this can- 
vas (/Canvas). When an event matches the 
interest, the callback is executed with the event 
on the stack. 

- /Makeinterests interest list 

This method returns an array of the interests of 
this canvas. It is overridden to express addi- 
tional interests in events over this canvas and to 
specify callbacks to execute when those events 
occur. As an example, consider: 

/Makeinterests { 

/Makeinterests super send 

PointButton Imy-method /DownTransition Canvas 
/Makeinterest self send 

}def 
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/Mapped 

/Menuinterest 

/MgrOwner? 

/PaintCanvas 

/Paint ScrolledArea 
/Set Active 



This procedure sends /Makeinterests to its 
superclass to get any interests expressed there. 
The procedure then adds an interest in down 
transitions of the POINT button over this can- 
vas, using the /Makeinterest method. 

- /Mapped bool 

Returns true if the canvas is mapped; the default 
is the same value as /Transparent. 

- /Menuinterest interest 
Returns the menu interest of the canvas. 

- /MgrOwner? bool 

Returns true if this canvas created its own event 
manager. 

- /PaintCanvas 

Paint the entire canvas. Subclassers will want to 
override this method to correctly paint the can- 
vas. 

dx dy /PaintScroUedArea - 

This method is called by /scroll to paint the 

area of the canvas that was scrolled. 

bool /Set Active - 



/SetGlobalCursor 



/SharedDamage? 



/SharedHelp? 



/SharedMenu? 



/cursor /cursormask | 
null /SetGlobalCursor 

- /SharedDamage? bool 

Indicates that an interest in damage should be 
expressed if the canvas is opaque. 

- /SharedHelp? bool 

Indicates that an interest in the help key should 
be expressed if there is a help procedure. 

- /SharedMenu? bool 

Indicates that an interest in the MENU button 
should be expressed if there is a menu associ- 
ated with the canvas. 



Interface Reference 



11-45 




Interface Reference 



/Siblings+ 



/Siblings- 



/StrokeAndFillCanvas 



/StrokeCanvas 



/StrokeColor 

/TextColor 

/TextEncoding 



/TextFamily 

/TextFont 

/TextSize 

/Transform 



canO I null /Siblings+ canO canl can2 ... | 

Return the NeWS canvases with the same parent 
as this canvas, including this canvas. The array 
is ordered by how the canvases would be lay- 
ered on the screen bottom first to top last. This 
method is used by siblings+. 

canO I null /Siblings- canO canl can2 ... | 
Return the NeWS canvases with the same parent 
as this canvas, including this canvas. The array 
is ordered by how the canvases would be lay- 
ered on the screen top first to bottom last. This 
method is used by siblings-. 

edgecolor inset 

fillcolor /StrokeAndFillCanvas - 
Draw a border which is inset wide around the 
canvas using edgecolor, and fill the interior with 
fillcolor. 

color inset /StrokeCanvas - 

Draw a border inset units inside the canvas (in 

CTM) stroke it with color. 

- /StrokeColor color 
Return the stroke color. 

- /TextColor color 
Return the text color. 

- /TextEncoding array 

Returns the canvas's PostScript language encod- 
ing vector, an array containing the mapping of 
character names to character codes 

- /TextFamily name 

- /TextFont font 

- /TextSize integer 

Returns the current point size of text. 

X y w h /Transform x' y^ w' h' 

This method is overridden to change the default 
CTM of the canvas. The following example 
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/XOYOFromUser 

Class Variables 

/Active? 

/AutoTargetMenu 

/BorderStroke 

/CanvasMenu 

/CursorFont 

/Cursorlmage 

/CursorMask 

/Cursors 

/DragFraitie? 

/EventMgrSet? 



shows /Transform overridden to map the coor- 
dinates of a canvas onto the unit square.. nf 

/Transform { % x y w h => x’ y* w* h’ 

4 2 roll translate scale 0 0 11 
}def 

- /XOYOFromUser x y 

Block until the user clicks the mouse on this can- 
vas; return the location of the mouse click. 



This variable is true if the canvas is ready for 
user interaction. 

This variable is true if the canvas automatically 
sets itself as the target object of its installed 
menu when the menu is shown. 

This variable is the size of the border around the 
canvas when painted by /PaintCanvas. 

This variable stores the canvas's menu. 

This variable stores the default cursor font of the 
canvas. 

This variable stores the default cursor image of 
the canvas. 

This variable stores the default cursor mask of 
the canvas. 

This variable stores a dictionary containing the 
cursor objects of the canvas. 

This variable indicates whether to drag the can- 
vas (false) or just a wire frame (true) when mov- 
ing the canvas. 

This variable is true if the canvas has an event 
manager. 
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/Event sConsuined 

/HelpProc 

/KeyConsumer? 

/LastFocusTime 

/Retained 

/SaveBehind 



/StdCursorFont 

/Transparent 

see also: 

Object 



This variable stores a list of all the events the 
canvas consumes. 

This variable stores the canvas's help procedure, 
if it has one. 

This variable is true if the canvas is interested in 
keyboard input, regardless of whether the can- 
vas actually consumes them or passes them on. 

This variable stores the last time the canvas had 
the input focus. 

This variable is true if the canvas is retained. 

This variable is the NeWS /SaveBehind hint to 
the server about how to handle damage to 
underlying canvases when this canvas is put on 
screen. 

This variable stores a dictionary of cursor fonts. 
This variable is true if the canvas is transparent. 



ClassCommandFrame 

Subclass of ClassFrame 
Source file: frame.ps 

This class should be subclassed rather than directly instantiated. 

This class is not for direct use; rather it supports frame (window) subclasses, 
such as the OPEN LOOK window frames. If you need a simple window frame 
for immediate use, consider one of the OPEN LOOK frames: 

■ OpenLookBaseFrame 

■ OpenLookPropertyFrame 
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■ OpenLookNoticeFrame 

■ OpenLookCommandFrame 

■ OpenLookHelpFrame 

see also: 

ClassFrame 



ClassContainer 

Subclass of ClassBag 
Source file: bag.ps 

This class can be directly instantiated, but is usually subclassed. 

A container is a bag with defined border areas and a special client, named 
/Client. When the bag is reshaped, the bag takes for itself a fixed amount of 
space for the borders, specified by class variables. All remaining space goes to 
/Client. 

Examples of subclasses of ClassContainer are frames and panes. 



Direct Methods 

/client 



/destroy 



/destroydependent 



/fitclient 



- /client client | null 

Return the container's designated main client, 
the /Client object, or null if empty. 

- /destroy - 

Destroy the container and its client. Refer to 
jdestroy in ClassBag for more information on this 
method. 

- /destroydependent 

Override this method for any client that should 
not be destroyed at the same time as the con- 
tainer and other clients. 

w h /fitclient w' h' 

Add the container's borders to the size of 
/Client to obtain the size the container must be 
to fit a client of the given size. 
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/location 



/minsize 



/move 



/new 



/newinit 



/preferredsize 



- /location X y 

Return the location of the bag's origin in CTM 
coordinates. 

/minsize minwidth minheight 
The minimum size for a container is by default 
the minimum size of /Client with the border 
sizes added. 

X y /move ^ 

Move the origin of the container to the point 
(x,y) in the coordinates of the CTM. 

client I null parentcanvas /new instance 

clientclass parentcanvas /new instance 

[args clientclass] parentcanvas /new 
instance 

This method creates a new container, calling 
/newinit to perform initialization once the 
instance is created. The arguments to /new are: 

■ the parent canvas of the container being 
created 

■ the client canvas of the container, or the 
class from which to create an instance to 
be the client, or null. The client instance 
or the class to be instantiated forms See 
/addclient in ClassBag for more details on 
specifiying the client instance or a class to 
be instantiated. 

client I null /newinit 

This method is called from /new and consumes 
the client argument while initializing the new 
client. 

- /prefeiredsize preferredwidth prefer- 
redheight 

Calculate the preferred size of the container, by 
default, the preferred size of its designated client 
plus the size of border areas. 
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/reshape 



/setclient 



/size 



/unfitclient 



X y w h /reshape - 

Reshape the container to the given size. Later, 
during layout the borders (and any secondary 
clients) are given their fixed amount of space, 
and the designated client absorbs all remaining 
space. 

newclient | null /setdient oldclient | null 
Set /Client for the container; return the previous 
/Client or null if there was none. Supplying 
null removes the existing client, if there was 
one, without setting a new one. 

- /size w h 

Return the current size of the container in the 
coordinates of the CTM. 

w h /unfitclient w' h' 

Subtract the borders from the size of the con- 
tainer to obtain the size /Client must be to fit 
into the container. 



Subclass Methods 

/BorderHeights 



/BorderWidths 



/LayoutClient 



- /BorderHeights nuniber 

This method returns the total border height of 
the container, the sum of the heights of the 
header at the top plus the footer at the bottom. 
Override this method if your container has a dif- 
ferent layout or geometry. 

- /BorderWidths number 

This method returns the total border width of 
the container, the sum of the widths of the left 
and right borders. Override this method if your 
container has a different layout or geometry. 

- /LayoutClient - 

Position the client in the container as specified 
by the Border variables: 
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■ /BorderLeft units from the left edge, 

■ /BorderRight units from the right edge, 

■ /BorderBottom units from the bottom, and 

■ /BordeiTop units from the top. 

Override this method for containers with a 
different arrangement or geometry. 



Class Variables 

/BorderBottom 



/BorderLeft 



/BorderRight 



/BorderTop 



This variable should be overridden to define 
how far from the bottom of the container the 
client is placed. 

This variable should be overridden to define 
how far from the left edge of the container the 
client is placed. 

This variable should be overridden to define 
how far from the right edge of the container the 
client is placed. 

This variable should be overridden to define 
how far from the top of the container the client 
is placed. 



ClassControl 

Subclass of ClassCanvas.ClassTarget 
Source file: control.ps 



This class should be subclassed rather than directly Instantiated. 

A control is a canvas that responds to user input with visual feedback. A con- 
trol consists of: 
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■ a value and some way to dynamically display it on screen. 

The value can be any PostSaipt language object, although subclasses usu- 
ally restrict the value. 

■ a notification procedure, or callback, 

which is called whenever the control's value changes as the result of user 
interaction. The notification procedure is executed with the control object 
on the operand stack, and can therefore find any specific information 
about the control (for example, its value); 

■ a target object 

to which the notification procedure can send a message. Often, user 
action on a control will do more than simply change the control's value. 
The target allows the control to specify another object to notify with its 
callback procedure. For example, if you want a menu to appear in 
response to pressing a mouse button over a control, you would make the 
menu the target for the control's callback. 

■ a tracking process, 

which is a simple event manager that watches for activity on a mouse but- 
ton identified in the class variable /ControlButton. (Usually the SELECT 
button is designated.) The tracking process is initiated when the button is 
pressed and watches for /MouseDragged, /EnterEvent, /ExitEvent and 
/UpTransition events. When the /UpTransition occurs the notification 
procedure is executed. 

■ a state of enabled or disabled: 

when the control is disabled, it no longer responds to user input. Usually, 
the functioiuility that displays the control's value will indicate the 
control's state as well 

The simplest example of a directly usable control is OpenLookButton. In this 
case the control's value is represented with a graphic (an instance of a subclass 
of QassGraphic). The graphic is drawn (and redrawn) to represent the value of 
the graphic, having a different appearance when enabled than when disabled. 
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Direct Methods 

/activate 



/active? 



/callnotify 



/checknotify 



/cleartarget 



/deactivate 



/destroy 



/disable 



- /activate - 

Activate event management for this control; 
express the interests returned by the /makein- 
terests method. Create an event manager for 
the control if one cannot be found in one of its 
parent canvases. An application does not usu- 
ally call this method directly. Instead, controls 
are commonly grouped together in a bag, and 
the bag controls activation for all of its clients. 

- /active? bool 

Return true if event management has been 
activated on the control. 

- /callnotify 

Call the control's notify procedure uncondition- 
ally, with the control itself on the operand stack. 

object I null /checknotify 
This method sends /CallNotify? to the control 
and if true is returned, the notify procedure is 
called. This mechanism provides conditional 
notification based on criteria specified by the 
subclasser in overriding /CallNotify?. 

object I null /cleartarget - 
Selectively clear the target. If null is given, set 
the target to null. If an object is given, set the 
target to null only if the target is the object. 

- /deactivate 

Turn off event management for this control. If 
the event manager is owned by this control, des- 
troy it. 

- /destroy - 

Turn off tracking if it is on, and destroy the con- 
trol. 

~ /disable - 

Set the control to the disabled state, in which 
user interaction is not allowed. Generally the 
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/enable 



/enabled? 



/location 



/minsize 



/move 



/new 



/newinit 



/notifiedvalue 



/notifyproc 



appearance of the control on screen changes 
whed disabled. 

- /enable - 

Set the control's state to enabled, and display it 
accordingly with /PaintEnabledState. 

- /enabled? bool 

Return true if the control is currently enabled, 
false if it is disabled. When disabled, the con- 
trol does not respond to user input. 

- Aocation x y 

Return the location of the origin of the control 
relative to the CTM. 

- /minsize w h 

Return the smallest size the control can be and 
still appear intelligible. 

X y /move 

Move the origin of the control to the specified 
location in the coordinates of the CTM. 

{notifyproc} I null parentcanvas /new - 
Create a new instance of the control, specifying 
the control's parent canvas and its notification 
procedure. When subclassing, additional argu- 
ments consumed by /newinit should appear 
before the notification procedure. 

(notifyproc} I null /newinit - 
This method is called from /new to after creat- 
ing an instance, /newinit does superclass initial- 
ization, sets the notify procedure to the supplied 
argument and initializes the variable that stores 
the control's last notify value. 

- /notifiedvalue any 

Return the value the control had the last time 
the notification procedure was called. 

- /notifyproc proc 

Return the control's current notify procedure. 
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/preferredsize 



/reshape 



/sendtarget 



/setnotifyproc 



/set target 



/set value 



/size 



/target 



/trackinterests 



- /prefeiredsize width height 

Return the control's preferred size. For nwst 
controls (except OPEN LOOK scrollbars), this 
will be the minimum size, /minsize. 

X y w h /reshape - 

Reshape the control to fit the bounding box 

specified by the arguments, in the coordinates of 

the CTM. This method allows the toolkit or the 

application to position the control on its parent 

canvas. 

args /method /sendtarget results 
Send method and its arguments to the current 
target object. This method is often used inside 
the control's notification procedure to send a 
message to the target object of the control. 

proc /setnotifyproc - 

Set the control's notify procedure, overwriting 

the previous one. 

object /settaiget 

Set the target object for the control. This should 
be done just after the control is created, before 
the notification can be invoked. Sending a mes- 
sage to a nonexistent target results in an error. 

any /setvalue - 

Set the value of the control. It is a subclass 
issue to define the set of legal values for a con- 
trol, and what action to take given an illegal 
value. 

- /size w h 

Return the width and height of the control in 
the coordinates of the CTM. 

- /target object 

Return the target object of the control. 

- /trackinterests [Interests] 

Return an array containing the tracking interests 
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/trackmgr 



/trackoff 



/trackon 



/value 



of the control. This method is not usually called 
directly by an application. 

- /trackmgr e ventmgr I nul 1 

Return the tracking event manager for this con- 
trol. 

- /trackoff - 

Turn tracking off for the control. Destroy the 
tracking event manager as soon as it has han- 
dled any pending events. 

This method is not usually called directly by an 
application, but is invoked automatically 
through /StopTracking when the user releases 
/ControlButton after pressing it over the con- 
trol. 

- /trackon - 

Turn on tracking in response to the user press- 
ing the indicated mouse button (/ControlButton) 
over the control. If there is no tracking event 
manager, create one and call /MakeTrackln- 
terests to express the control's tracking interests. 

This method is not usually called directly by an 
application, but is invoked automatically 
through /StartTracking when the user presses 
down /ControlButton over the control. 

- /value any 

Return the current value of the control. The set 
of values will be restricted by most subclasses, 
which have the responsibility for ensuring that 
illegal values do not get stored. 
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Subclass Methods 

/BuildTracklnterest 



/CallNotify? 



/ClientDown 

/ClientDrag 

/ClientEnter 

/ClientExit 

/ClientRepeat 



name action canvas 

method /BuildTracklnterest interest | - 
This method is called by /MakeTrackInterests to 
build one interest from the arguments supplied. 
The mme, action, and canvas arguments go into 
the interest as their respective key values. 
method is the name of the callback procedure; it 
is a method in the control class that handles the 
event 

object I null /CallNotify? bool 
Override this method to define the criteria for 
calling the notification procedure. The default 
criterion is that the current value of the control 
is different than the value when the last 
notification was performed (/NotifiedValue). 

event /ClientDown 

Override this method to implement special 
behavior at the start of tracking. 

event /ClientDrag 

Override this method to provide a tracking 
interest callback for every mouse movement 
inside the control. 

event /ClientEnter 

Override this method to provide a tracking 
interest callback for mouse movements into the 
control. 

event /ClientExit - 
Override this method to provide a tracking 
interest callback for mouse movements out of 
the control. 

event /ClientRepeat - 
a periodic action controlled by the /Clien- 
tRepeatTime and /ClientStartTime variables. 
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/ClientUp 



/EndTracking 



/EventHandler 



/EventToXY 



/MakeTrackInterests 



/PaintEnabledState 



event /ClientUp - 

Override this method to implement special 
behavior at the end of tracldng. 

event /EndTracking - 
This method is called automatically in response 
to a tracking interest in the /UpTransition of the 
/ControlButton. It calls /ClientUp to do any 
special handling (none by default) and then 
turns off tracking with /trackoff . 

event /EventHandler 

When the control is initialized, it expresses an 
interest in /ControlAction on the /ControlBut- 
ton, with this method as the callback. By 
default, the interest is in the /DownTransition of 
the PointButton. When an event occurs that 
matches the interest, this method is called with 
the event on the operand stack. 

Override this method to define the control's 
behavior when that event occurs. Typically, the 
override will include a call to/StartTracking. 

event /EvenlToXY x y 

Extract the XLocation and YLocation from the 

event, and return them. 

~ /MakeTrackInterests [ int e rests] 

Override this method to specify which tracking 
interests a subclass needs. This method is called 
from /trackinterests to generate an array of 
interests 

bool /PaintEnabledState -* 

Override this method if the control's appearance 
on screen depends on whether it is enabled or 
disabled. This method is called by /enable and 
/disable: 

■ with the control as the current canvas 
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/PaintValue 



/StartTracking 



Class Variables 

/Active? 

/ClientRepeatTirae 

/ClientStartTime 

/ControlAction 



■ inside gsave ^ grestore 

■ with the boolean arguments true and false 
respectively. 

newvalue /PaintValue - 
This method is SubQassResponsibility and must 
be overridden to display the value of the con- 
trol. 

Subclassers should note that this method is 
called by /setvalue with the control's new value 
on the stack, while the previous value is still 
available through /value. Thus, old and new 
values of the control are both available to this 
method if it needs them, for example, to per- 
form incremental painting. 

event /StartTracking 

Start event tracking for this control, if the con- 
trol is enabled. This method is called in 
respoitse to a tracking interest in the /Down- 
Transition of the ControlButton. It calls 
/ClientDown to do any special handling (none 
by default) and then turns on tracking with 
/trackon. 



This variable is true if the control has event 
management turned on. 

This variable is the interval for a timer interest 
controlling when the /ClientRepeat method is 
called. 

This variable is the starting time for a timer 
interest controlling when the /ClientRepeat 
method is called. 

This variable specifies the action of the /Control- 
Button that starts tracking. By default it is the 
/DownTiansition. 
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/ControlButtorv This variable specifies which mouse button the 

control is interested in, by default it is the 
PointButton. 



see also: 

ClassCanvas,ClassTarget 



ClassDialControl 

Subclass of ClassControl 
Source File: dial.ps 

This Class should be subclassed rather than instantiated. 

ClassDialControls is the basis for “analog" controls, which have a bounded 
numerical value that changes in resonse to user interaction. Conunonly used 
dial controls are scrollbars and sliders. 

see also: 

ClassControl, OpenLookVerticalScrollbar 



CiassFrame 

Subclass of ClassContalner 
Source file: frame.ps 

This class should be subclassed rather than directly instantiated. 

CiassFrame is designed for the management of windows (frames) on the frame- 
buffer. It is an instrinsic class supporting the OpenLook frames: 

■ OpenLookBaseFrame, 

■ OpenLookCommandFrame, 

■ OpenLookHelpFrame 

■ OpenLookIconFrame 

■ OpenLookNoticeFrame 

■ OpenLookPropertyFrame 
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see also: 

ClassContainer, OpenLookBaseFrame 



ClassHelpFrame 

Subclass of ClassFrame 
Source file: frame.ps 

This class should be subclassed rather than directly instantiated. 

This class is not for direct use; rather it supports subclasses of window frame, 
such as the OPEN LOOK window frames. If you need a simple window frame 
for immediate use, consider one of the OPEN LOOK frames: OpenLook- 
BaseFrame, OpenLookPropertyFrame, OpenLookNoticeFrame, OpenLookCom- 
mandFrame, OpenLookHelpFrame. 

ClassIconFrame 

Subclass of ClassFrame 
Source file: frame.ps 

This class should be subclassed rather than directly Instantiated. 

This class is not for direct use; rather it supports frame (window) subclasses, 
such as the OPEN LOOK window frames. If you need a simple window frame 
for immediate use, consider one of the OPEN LOOK frames: OpenLook- 
BaseFrame, OjjenLookPropertyFrame, OpenLookNoticeFrame, OpenLookCom- 
mandFrame, CipenLookHelpFrame. 

ClassMenu 

Subclass of ClassSelectionLlst 
Source file: menu.ps 

This class should be subclassed rather than directly instantiated. 

This class is suports hierarchical, pop-up, pinnable menus. It is not immediately 
instantiatable, but forms the underpinning for OpenLookMenu. 
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CiassPropertyFrame 

Subclass of ClassFrame 
Source file: frame.ps 

This class should be subclassed rather than directly instantiated. 

This class is not for direct use; rather it supports frame (window) subclasses, 
such as the OPEN LOOK window frames. If you need a simple window frame 
for immediate use, consider one of the OPEN LCX)K frames: OpenLook- 
BaseFrame, OpenLookPropertyFrame, OpenLookNoticeFrame, OpenLookCom- 
mandFrame, OpenLookHelpFrame. 



ClassSelectionList 

Subclass of ClassCanvas,ClassTarget 
Source file: selectlst.ps 

This class should be subclassed rather than directly instantiated. 

In a selection list, a single canvas maruiges a grid of regularly spaced items 
which can be independently selected via the mouse. This class is the basis for 
menus (OpenLool^enu) and setting controls (Exclusive, NonExclusive, and 
Choggles). 



ClassTarget 

Subclass of Object 
Source file: target.ps 

This class can be directly instantiated. 

ClassTarget, typically used as a mix-in class, provides facilities to any class 
whose instances need to send messages to other objects. Controls and menus 
are examples of such classes, as callbacks from these classes t)T?ically involve 
sending a message to some other object. The target connection is one-way and 
is maintained as long as the targeted object persists. 
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The connection is actually implemented as a soft reference to the targeted object. 
If the targeted object should become obsolete the soft reference is removed and 
the target is set to null. 



Direct Methods 

/cleartarget 



/destroy 



/sendtarget 



/settarget 



object! nu 1 1 /clcartaiget 
Selectively clear the target. If null is given, the 
target is cleared. If object is given, the target is 
cleared only if the object and the traget are the 
same. This ensures that the target cannot be 
incorrectly cleared. 

- /destroy - 

Clear the target (with /cleartarget) and then 
proceed with the normal object destruction. 

args /method /sendtarget results 
Send the method and arguments to the targeted 
object. Any menu or control can have a "target” 
which you can set, get, and send to. For exam- 
ple, if you have a button that needs to send a 
message to object foo when the button's callback 
is executed: 

/b (Hello) {Ifoo-method /sendtarget 3 -1 roll send} 
framebuffer /new OpenLookButton send def 

foo /settarget b send 

When the button is pressed, foo-method will be 
sent to foo. 

You can change the target at any time if you 
want to make your control send to different 
objects at different times. An error results from 
sending anything to a null target. 

object /settaiget ~ 

Set the target object, overwriting the previous 
target, if there was one. 
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/target - /target object 

Return the target object, which has a soft refer- 
ence to it. 



Subclass Methods 

/ChangedTarget 



/FreshTarget 



/ObsoleteTarget 



/RemovedTarget 



old-target /ChangedTarget 
This method is called whenever a target 
changes. Override it to add special processing if 
necessary. 

- /FreshTarget - 

This method is invoked whenever the target is 
changed from null to an object. Override this 
method to provide special processing for this 
case. 

/ObsoleteTarget 

This method is called when the target becomes 
obsolete. Override it to add special processing. 

/RemovedTarget - 

This method is called whenever a target is 
removed (becomes null). Override this method 
to provide special processing for this case. 



see also: 

OpenLookMenu, ClassControl 



ClassTextControl 

Subclass of ClassControl 
Source file: txtctrlps 

This class should be subclassed rather than directly instantiated. 

A text control accepts user keystrokes, displays them and calls the supplied 
notify proc. It interacts with the Ul-independent selection mechanism, providing 
simple text selections. 
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Direct Methods 

/callnotify 



/checknotify 



/cleartarget 



/delchar 



/delspan 



/delword 



- /callnotify - 

Call the client's notifyproc, and also make a 
copy of the string. The copy will not be affected 
by subsequent user keystrokes, so /checknotify 
will be able to determine whether the value has 
changed. 

object I null /checknotify 
Call the client's notifyproc only if the current 
text differs from the text as of the last call to 
/callnotify. This method is called automatically 
when the text control loses the input focus, or 
when the user types the RETURN key. 

object I null /cleartarget - 
Selectively clear the target used by the /sendtar- 
get method. This method is called automatically 
when the text control is destroyed. See ClassTar- 
get for more about targets and their uses. 

n /delchar - 

Delete n characters from the text, starting at the 
current caret position. If n is negative, delete 
characters to the left of the caret, otherwise to 
the right. 

left rightplusone /delspan - 
Delete a span of characters from the text, 
independent of where the caret is. If the caret 
and/or a selection is within the deleted region, 
it is adjusted accordingly. Qiaracter positions 
start with zero; thus left is the number of char- 
acters before the first to be deleted, and the 
number of characters deleted is rightplusone 
minus left. 

- /delword 

Delete characters backward from the caret posi- 
tion until (a) at least one alphanumeric has been 
deleted and (b) the character ahead of the caret 
is not alphanumeric. The method 
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/demo 



/destroy 



/disable 



/enable 



/enabled? 



/fitcaret 



/fontof fset 



/AlphaNumeric? is used to determine whether a 
character can be part of a word. 

- /demo instance 

Create a sample text control whose parent is the 
framebuffer. The control is actually an instance 
of the default subclass (i.e., OpenLookTextCon- 
trol). 

- /destroy - 

Destroy this control. In addition to clearing the 
target and removing the canvas from the canvas 
tree, etc., this method disables the caret, in case 
for example the caret needs to stop a forked 
process used to implement blinking. (The 
default ClassCaret does not.) 

- /disable - 

Cause the control to stop responding to user 
actions. The control repaints to display its dis- 
abled status, and will no longer accept the input 
focus. 

- /enable - 

Cause the control to respond to user actions, 
provided that it is not a read-only text control. 
The control repaints to display its enabled 
status, and will become the input focus if the 
user clicks the mouse over it. 

- /enabled? bool 

Return true if the control is currently enabled, 
even if it is read-only. 

- /fitcaret - 

Call /FitCaret, which does nothing in this class. 
Subclassers may override /FitCaret to provide a 
method that brings the caret into the visible 
region of the control. 

- /fontoffset int 

Compute the vertical offset for drawing charac- 
ters without cutting them off at the bottom of 
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/inserttext 



/invisiblecaret 



/location 



/rainsize 



/move 



the canvas, and also leaving enough room for 
the caret. The value is 'promoted', i.e., the first 
time /fontoffset is called it stores the resulting 
value in the instance under the name /fontoffset, 
so that subsequent calls are much faster. The 
cached value is discarded (unpromoted) if the 
canvas becomes invalid, e.g. if /settextparams is 
called. 

char /inserttext 
string /inserttext - 

Insert a character or a string into the text at the 
current caret position. The caret is moved to the 
end of the inserted text. If a pending-delete pri- 
mary selection spans the caret, the selected text 
is deleted before adding the new text. Any other 
existing selections are adjusted appropriately. 

- /invisiblecaret 

Make the caret invisible, usually in preparation 
for other operations that will cause painting. 

This method is not normally used at all, since 
the methods that cause painting (such as /insert- 
text, /delchar, etc.) all call /InvisibleCaret, which 
assumes that the text control is the current can- 
vas. 

- /location x y 

Return the location of the origin (lower left 
comer) of the text control relative to the CTM. 

- /minsize mlnwidth minheight 

Return the minimum size for this control. The 
minimum height is determined by the font size, 
and the width is determined by fi\e font and by 
the number of characters that the control is sup- 
posed to leave room for, as set using /set- 
displaychars. 

X y /move 

Move the origin (lower left) of the text control to 
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/new 



/newinit 



/notifiedvalue 



/notifyproc 



/painttext 



/preferredslze 



the specified location in the coordinates of the 
CTM. 

callback parent /new instance 
Return a new text control instance with the 
specified callback procedure 
and parent canvas. The control initially contains 
no text, but does contain a caret. 

callback /newinit - 

This method does /newinit super send to store 
the callback procedure, then performs other ini- 
tialisation specific to text controls. 

- /notifiedvalue string 

Return the value the control had the last time 
/callnotify was sent. 

- /notifyproc proc 

Return the current callback proc without invok- 
ing it. 

n /painttext 

Paint the text, starting with the character at posi- 
tion n. If character n is off the left edge of the 
canvas, painting starts at the edge of the canvas. 
If n < 0, all the text is painted and the remainder 
of the canvas is cleared; otherwise the canvas is 
left unchanged beyond the end of the text. This 
method is intend^ mainly for use from other 
methods; clients should generally send /paint to 
paint the control, /painttext operates by setting 
the current canvas and font, ^en calling the 
internal methods /InvisibleCareb /FaintText, 
and /VisibleCaret 

- /preferredslze width height 

Text controls do not presume any preferred size 
beyond the minimum required to display a cer- 
tain number of characters. Thus they use the 
default /preferredslze method, which simply 
calls /minsize. 
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/remove focus 



/reshape 



/restorefocus 



/scroll 



/sendtarget 



/setcolors 



/setdisplaychars 



event /removefocus - 

Handle the input focus being moved to another 
canvas. This method disables the caret and calls 
/checknotify, which calls the client's notifyproc 
if the text has been changed. 

X y w h /reshape - 
Reshape the control to fit the bounding box 
specified by the arguments, in the coordinates of 
the CTM. 

- /restorefocus - 

Activate the caret if the control is enabled. 

This method is called automatically when the 
text control is given the input focus. 

n /scroll - 

Scroll the text to make a different portion visible 
within the limits of canvas. The left edge of the 
canvas always marks the beginning of a charac- 
ter; scrolling changes the character at this loca- 
tion. A positive number nn scrolls to the right; a 
negative number scrolls to the left. 

args /method /sendtarget results 
This method can be invoked within the 
notifyproc in order to send a message to some 
other instance. Many clients will not need to use 
this indirection. See ClassTarget for more details. 

strokecolor fillcolor 
textcolor /setcolors - 
Set the colors for painting the text and its back- 
ground (fillcolor). Null as an argument means 
do not change that value. The control swaps the 
fillcolor and textcolor to highlight selections. 
Subclasses may use the strokecolor for underlin- 
ing or similar ornamentation, though OpenLook- 
TextControl uses the textcolor so that it can be 
included in the highlighting. 

n /setdisplaychars - 

Set the minimum number of characters that the 
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/set not i f yp roc 



/setposition 



/set readonly 



/settarget 



/settextparams 



control should be able to display. This number 
is used in computing /minsize for the control. 
The number can be retrieved via the /Display- 
Chars variable. 

proc /setnotifyproc - 

Store the proc as the new callback to be used by 
/callnotify, in place of the one provided to /new. 

event /setposition - 
n /setposition - 

Move the caret to the specified position. Position 
0 puts the caret to the left of the first character. 

If an event is given, the coordinates in the event 
are resolved to the nearest character boundary. 
The current caret location can be obtained from 
the variable /Left 

bool /setreadonly - 

Make the text read-only or not, depending on 
the bool. If the text becomes read-only, the can- 
vas is removed from the list of potential input 
foci; if it becomes writeable it is added back. A 
read-only text control behaves much the same as 
a disabl^ one (see /disable), the main difference 
being that a disabled control will typically be 
painted light gray, whereas a read-only one will 
paint normally. 

object /settaiget - 

Set the target used by the /sendtarget method. 
See ClassTarget for more about targets and their 
uses. 

family pointsize encoding /settextparams 
Set the text parameters that determine the font 
for the control. If any of the arguments is null, 
that paranaeter is not changed. The control then 
marl^ itself as invalid (i.e., calls /invalidate) so 
that various cached values such as /fontoffset 
and the font itself will be recomputed. 
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/set value 



/size 



/starttext 



/ St opt ext 



/strlen 



/target 



/value 



/visiblecaret 



string /setvalue 

Replace the contents of the text control with the 
given string. If the string differs from the old 
contents, the control is repainted. 

- /size w h 

Return the width and height of the control in 
the CTM. 

- /starttext - 

This method activates the caret. It is called from 
/restorefocus. 

- /stoptext 

This method disables the caret. It is called from 
/removefocus and /destroy. Clients may also 
need to send /stoptext to newly created text con- 
trols to disable their initial carets. 

- /strlen n 

Return the number of characters of text 
currently stored in the control. This method is 
equivalent to, but more efficient than, /value 
length. 

- /target object 

Return the current target (if any) used by 
/sendtarget See ClassTarget for nnore details. 

- /value string 

Return the contents of the control as a PostScript 
string. If the string is empty, a zero-length string 
is returned, not null. 

- /visiblecaret 

Make the caret visible, usually after other paint- 
ing has finished. This method is not normally 
u^ at all, since the methods that cause paint- 
ing (such as /inserttext; /delchar, etc.) all call 
/VisibleCaret, which assumes that the text con- 
trol is the current canvas. 
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Subclass Methods 

/AlphaNumeric? 



/CaretPosition 



/DeHighlight 



/EOL 



/FitCaret 



/Highlight 



n /AlphaNumeric? bool 

Determii\e whether the character at the specified 

index is part of a word. This method is called by 

/delword, and also when making word-level 

selections. The default nriethod texts for letters, 

digits, and underscore. See /AlphaNumericT- 

able. 

- /CaretPosition x 

Return the x-coordinate of the caret relative to 
the left edge of the canvas. 

start end /DeHighlight last 
Paint the characters in positions sfarfstart 
through end-1, and return the index of the next 
character to be painted. The characters are 
painted using the canvas's /FillColor as back- 
ground and /TextColor for the text and under- 
line. This method is called by /PaintText and in 
turn calls /PaintNTexL 

- /EOL - 

This method is called when either a RETURN 
CM) or NEWLINE CJ) character is typed into 
the control. It calls /checknotify. 

/method /FitCaret bool 
Scroll the text if desired so as to bring the 
current caret position into the region between 
the left and right edges of the canvas. Return 
true if any scrolling was done, so the caller will 
know to repaint the text. (/FitCaret does not 
itself do any painting.) The parameter is the 
name of the operation just performed, one of: 
/delspan, /fitcareL /inserttexL or /setposition. 

The default /FitCaret never does any scrolling. 
Subclassers may override this behavior to cause 
scrolling after selected operations. 

start end /Highlight last 

This is the same as /Deliighlight (q.v.) except 
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/InterestingRank 



/InvisibleCaret 



/PaintText 



/PaintNText 



the background and foreground colors are 
reversed. It is called by /PaintText for painting 
characters within the primary selection. 

rank /InterestingRank bool 
Return true if the selection rank is one that the 
text control knows how to deal with. By default 
the only interesting ranks are /PrimarySelection 
and /SecondarySelection. (/ShelfSelection is 
handled by the global UI mechanism.) For each 
interesting rank there is also a correspondingly 
named instance variable, used for maintaining 
information about that selection. (These vari- 
ables are of no interest to clients or subclassers, 
except insofar as subclassers must be careful not 
to use those variable names for other informa- 
tion.) 

- /InvisibleCaret 

Send a message to the caret to make it vaiush, 
usually in preparation for other painting. This 
method assumes that the text control is the 
current canvas. Many methods use the 
sequence; /TextBegin, /InvisibleCaret, p>aint 
some portion of the text, /VisibleCaret, /Tex- 
tEnd. 

n /PaintText - 

This method performs most of the work of 
/painttext (q.v.). It can assume that the text 
control's canvas is the current canvas, and the 
control's font is the current font. Subclassers 
may override this method to provide additional 
painting; e.g., OpenLookTextControI repaints the 
scroll buttons after the text is drawn. 

textcolor backcolor start 

end /PaintNText last 

This method is called by /Highlight and 

/DeHighlight to paint portions of the text using 

the given colors for the text and background. 

The characters painted are those in positions 
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/Scroll 



/TextBegin 



/TextEnd 

/VisibleCaret 



Class Variables 

/AlphaNumericTable 
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sfarf start through endend-1. This range may be 
empty. /PaintNText returns the index of the 
next character to be painted, the larger of 
endend and startstart This method assumes that 
the text control is the current canvas and the 
control's font is the current font. 

n /Scroll 

This is the same as /scroll except no painting is 
done. Subclassers may use /Scroll when over- 
riding /FitCaret, to perform scrolling while leav- 
ing any painting for later. 

- /TextBegin - 

Save the graphics context, then set the text 
control's canvas and font as the current canvas 
and font. This method is called at the beginning 
of several other methods to establish the context 
for painting and other CTM-based operations. 

- /TextEnd 

Restore the graphics context saved by /TextBe- 
gin. 

- /VisibleCaret - 

Send a message to the caret telling it to become 
visible, and where it should be located. This 
method assumes that the text control is the 
current canvas. 



This is a dictionary whose keys are single char- 
acters (integers). The associated values are 
ignored. A character appears as a key if and 
only if that character is considered part of a 
word. This dictionary is used by 
/AlphaNumeric?, and can be overridden by sub- 
classers to change the definition of word- 
selection and /delword. Note: Subclassers who 
wish to change this dictionary should be careful 
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to copy it first; otherwise the changes will affect 
all text controls. That is, do not subclass like 
this: 

%add dollarsign and percent to alphanumeric set 
AlphaNumericTabie begin 
($%) {null def} forall 
end 

Instead, write this: 

% add dollarsign and percent to alphanumeric set 
/AlphaNumericTabie dictbegin 
AlphaNumericTabie (def) forall 
($%) (null def} forall 
dictend def 

/DisplayChars The minimum number of characters that the 

control should be able to display. The default 
value is 5, unless overridden by subclassing or 
by /setdisplaychars. 

The number of characters to the left of the caret; 
hence, the current caret position. 

True if the control is read-only. This value 
defaults to false, but can be overridden by sub- 
classers or /setreadonly. 



/Left 

/Readonly? 

see also: 

ClassControl 



FlexBag 

Subclass of Class Bag 
Source file: bagutils.ps 

This class can be directly instantiated 

A FlexBag is a general purpose bag whose clients are layed out using executable 
code passed in with them during /addclient. FlexBags are particularly suited to 
the task of relative positioning. 
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name I null [client] /addclient - 

name I null [conpa88_point po8±tion_proc 

client] /addclient - 

The naming and instantiation of a flexbag client 
are the same as for QassBag. In particular, the 
client argument may be either an instance or a 
class to instantiate, with necessary arguntents. 
For more details, see the addclient method in 
ClassBag. 

If baggage is supplied, it consists of a reference 
point on the client (compass jnint) and a posi- 
tioning procedure ipositionjjroc) that determines 
where to place that point on the client in the 
bag. The client's reference point is specified 
with a compass-style notation: 

comers of the client: /nw, /sw, /ne, /se 
nudpoints of the client's edges: /n, /s, /e, /w 
center of the client: /c 

The positiotung procedure is any executable that 
returns an (x,y) coordinate location. This posi- 
tion is where the reference point of the client is 
placed when the flexbag is layed out. The pro- 
cedure can simply return two fixed values. Or, 
it can perform calculations of its own based on 
some intrinsic properties of the client. Or the 
position procedure can use the utility pro- 
cedures supplied by class FlexBag to perform 
positioning relative to other clients of the 
flexbag. These procedures (/HEIGHT, 

/WIDTH, /POSITION, /XYADD, /XYSUB) are 
described below. 

Note that both of the reference point and posi- 
tioning procedure may be unspecified, in which 
case a default value will be us^ (see /setlay- 
outspec). 
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/baggage 



/clientcount 



/clientlist 



/demo 



/destroy 



/layout spec 



/location 



/minsize 



client /baggage [coxnpas appoint 

pos it ion_jpr oc ] 

Return the positioning data for the client, its 
reference point in compass notation and its posi- 
tioning procedure. 

~ /dientcounf n 

Return the number of clients currently in the 
bag. 

- /clientlist [clientl client2 ...] 

Return an array of clients in the same order as 
they were inserted into the bag. 

- /demo franie__instance 

This method creates a sample flexbag that illus- 
trates the use of absolute, relative, and default 
positioning. The frame object that encloses the 
bag is left on the operand stack by /demo. To 
use this nr^thod be sure to load the demo code 
with the /IncludeDemos? flag. 

- /destroy - 

Destroy the bag and its clients. Refer to the 
/destroy method in ClassBag for the additional 
information on the use of this method. 

- /layoutspec coxnpas appoint positionjproc 

Return the default layout specification, which is 
used if no baggage was specified when adding a 
client to the bag. Initially, there is no default 
layout; it must be specified with /setlayoutspec. 

- /location x y 

Return the location of the origin of the bag in 
the coordinates of the CTM. 

/minsize minwidth minheight 
Compute the minimum acceptable size for this 
bag, based on the actual sizes of its clients and 
the padding between them. For a flexbag this 
requires a heuristic calculation. This problem 
can be circumvented by calling /lockminsize. 
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/move 



/new 



/padding 



/preferredsize 



/removeclient 



/reshape 



/sendclient 



/setbaggage 



/set layout spec 



X y /move - 

Move the origin of the canvas to the specified 
location in the coordinates of the CTM. 

parentcanvas /new instcuice 
Create a new flexbag. 

- /padding padding__width padding_height 
Return the sizes of the padding between clients 
used by /minsize to avoid unrelated clients 
being placed too close together. 

- /preferredsize preferredwidth prefer- 
redheight 

Calculate the preferred or "ideal" size of the 
bag, which by default is its minimum size. 

client I name I n /removeclient oldclient 
true 

client I name In /removeclient false 
Remove the client given, named or indexed in 
the argument. The method returns true and the 
client object if the client is found, otherwise it 
returns false. 

X y w h /reshape 

Reshape the bag to the dimensions given and 
invalidate it. This results in the bag being layed 
out as the first step in painting it. 

<args> /method /name /sendclient results 
Send the given method with arguments to the 
named client. An error results if the client is not 
present in the bag. 

client [con^ass_point 

position_proc] /setbaggage - 

Store the baggage for the bag. This consists of a 

compass point and a positioning procedure, as 

described under /addclient 

con^ass_point | null 

position_proc Inull /setlayoutspec 

Set the default positioning parameters for the 
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bag. This specification is used whenever a 
specification is not given when the client is 
added. If either argument is null, the 
corresponding parameter is not changed. 

/setpadding width height /setpadding 

Set the padding between clients used in calculat- 
ing the minumum size of the bag. 

/size - /size w h 

Return the width and height of the bag in the 
coordinates of the CTM. 



Utility Methods 

The following methods are defined in class HexBag for use in positioning clients 
of a flexbag. Used in the position procedure (.positionjjroc) of a client, they are 
executed by the /layout method of the bag. 

The client argument given to these methods can be: 

■ a client of the flexbag, 

■ Previous, indicating the previous client (the one that was layed out 
immediately before this client 

■ Current, indicating this client, 

■ self, indicating the flexbag. 



/HEIGHT 



/POSITION 



/WIDTH 



name | client /HEIGHT height 

Return the height of the given client, which may 

be specified either by name or by the client 

itself. 

con^ass_polnt name I client /POSITION xy 
Return the (x,y) position of the indicated com- 
pass point on the given client The client may be 
specified either by name or by the canvas itself. 

name I client /WIDTH width 

Return the width of the given client, which may 

be specified either by name or by the canvas 

itself. 
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/XYADD 


xl yl x2 y2 /XYADD xl+x2 yl+y2 
Return the vector sum of the two points given. 


/XYSUB 


xl yl x2 y2 /XYSUB xl-x2 yl-y2 
Return the vector difference of the two points 
given. 


see also: 

ClassBag 




Object 




Subclass of null 




Source File: Class.ps 


This class should be subclassed, even though It can be directly 


Instantiated. 




The class Object is the ultimate superclass of every class in the tNt toolkit. Much 


of the class system's 


functionality is implemented here. 


Direct Methods 




/class 


— /class class 




Sent to an instance, /class returns the class object 
from which this instance was created. 


/class? 


— /class? bool 




Return true if the object of the send is a class; 
false if it is an instance, or any other NeWS dic- 
tionary. 


/classinit 


— /classinit — 




This method is called automatically after class 
definition, but before any instances are created. 
Override it if you need to perform per-class ini- 
tialization that cannot be done as the class is 
being built. 


/classdestroy 


class /classdestroy — 

Remove a class from the system. This is a utility. 
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/classname 



/cleanout class 



/defaultclass 



/descendantof ? 



/destroy 



/ de St roydependent 



rather than a method. It is not sent to the class 
concerned, but consumes it as an argument. 

— /classname classname 

Sent to a class, this method returns the name of 
the class, sent to an instance it returns the name 
of the instance's class. 

— /cleanoutclass — 

Clean out a class dictionary for reuse. Whenever 
a class is redefined this method is called 
automatically. The effect of this is that instances 
or subclasses of the old class will immediately 
start using the new class code. 

— /defaultclass class 

Returns a default subclass if one has been 
defined, self otherwise. A default subclass is 
considered to be a reasonable subclass to instan- 
tiate for normal use. Many instrinsic classes 
have OPEN LOOK equivalents as their default 
subclass. 

instance i class /descendantof? bool 
Test to see if the argument is a descendant of 
the class or instance being sent to. 

— /destroy — 

Destroy this object. This method is called 
automatically when NeWS detects that there are 
no more hard references to it. Subclassers 
should override this method to break any circu- 
lar reference chains that include a soft reference 
to the object. When /destroy returns, all refer- 
ences to the object should have been removed. 

— /destroydependent — 

This method is sent to dependent objects (child 
canvases, and subframes are examples of such 
objects) in the process of destroying an object. 
Class Object imposes no semantics on what 
should happen to the dependent object in this 
case. 
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/doit 



/installmethod 



/instanceof? 



/name 



/named? 



/new 



/newdefault 



/newinit 



<args> proc /doit <results> 

Execute the given procedure from within the 
context of the object of the send. In particular 
self resolves to that instance, and super to its 
superclass. 

name proc /installmethod — 

Create or overwrite a method with the given 
name and given procedural body. This method 
can be sent either to a class or to an instance. In 
the former case the result of /installmethod is 
indistinguishable from having defined this 
method is the class originally. 

obj /instanceof? bool 

This method is sent to a class, not an instance. It 
returns true if the given object is an instance of 
the class. 

— /name name 

Return the name of an instance or class. If name 
was not set by /setname, then the name of an 
instance is the name of its class. Sending name 
to a class returns the classname unless the /set- 
name method has been applied to it. 

— /named? bool 

Returns true if the object of the send has had it's 
name set via the /setname method. This method 
can be sent to either an instance or a class. 

— /new instance 

Create an initialized instance of this class. This 
method should only be sent to a class. It calls 
/newobject followed by /newinit 

— /newdefault instance 

Create an instance using whatever /defaultclass 
returns. 

— /newinit 

Initialize an instance. Override this method to 
perform your per-instance initialization, and 
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/newmagic 

/newob ject 
/obsolete 

/?promote 

/promote 

/promoted? 

/set name 
/subclasses 

/superclasses 



consume any arguments that your subclass 
requires be presented to /new. 

<creation args> diet /newmagic instance 
Convert an existing magic dictionary object, into 
an object to which sends can be performed. The 
converted magic dictionary becom-es an instance 
of the class to which this message is sent. 

<creation args> /ncwobject instance 
Create an instance of a class, but do not initial- 
ize it. 

— /obsolete 

Handle an instance becoming 'obsolete'. This 
method will be sent when an instance loses its 
last hard references. By default, /obsolete calls 
/destroy to clean up the remaining soft refer- 
ences. 

name object /?promote 

Promote object to be an instance variable associ- 
ated with name only if the argument value is 
different from an existing instance variable 
value. 

name object /promote 

Promote object to be an instance variable whose 
name is the first argument. 

name /promoted? bool 

Return true if name is an instance variable, false 

otherwise. 

name /setname 

Set the name of a class or instance. 

— /subclasses [class . . . ] 

Return an array of class objects that are the 
currently defined immediate subclasses of the 
class to which this message is sent. 

— /superclasses array 

Return an array of class objects which define the 
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superclass chain for this class. The array is 
returned in order, from most distant to most 
immediate superclass. 

/understands? nanve /understands? bool 

Return true if name is defined in the context of 
the instance or class to which this mesasage is 
sent. 

/unp remote name /unpromote 

Remove a variable from an instance. No error 
will occur if no such variable existed. 

Subclass Methods 

/HandleObsoleteClass — /HandleObsoleteClass 

Called by /ObsoleteEventHandler when a class 
goes obsolete. By default this calls /destroyclass 

/HandleObsoletelnstance — /HandleObsoletelnstance — 

Called by /ObsoleteEventHandler when an 
instance goes obsolete. By default this calls 
/obsolete. 

/HandleObsoleteOther — /HandleObsoleteOther — 

Called by /ObsoleteEventHandler when an 
object that is not a a class or an instance 
becomes obsolete. 

/ObsoleteEventHandler event /ObsoleteEventHandler 

A callback method that is invoked by a global 
obsolete event manager when a class object 
becomes obsolete. Uses the /Action value in an 
event to call one of /HandleObsoleteClass, 
/HandleObsoletelnstance or /HandleOb- 
soleteOther. 
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Class Variables 

/ClassName 



/DefaultClass 



/ObsoleteEventMgr 



Class variable used to hold the name of the 
class. 

Variable referencing the default subclass of a 
class. This variable is self by default. Refer- 
enced by /defaultclass. 

A shared event manager whose job it is to call 
/ObsoleteEventHandler when an obsolescence 
event is received. 



OpenLookAbbrButton 

Subclass of OpenLookButton 
Source file: OLbUtton.ps 

This class can be directly instantiated 

This class implements OpenLook Abbreviated buttons: the graphic for the but- 
ton appears to the right of it, rather than inside it. This class is directly instanti- 
able, but is also mixed into OpenLookAbbrButtonStack. 



Direct Methods 

/callnotify 



/cleartarget 



/demo 



/destroy 



- /callnotify - 

Call the button's notify procedure uncondition- 
ally, with the button itself on the operand stack. 

object I null /cleartarget 
Selectively clear the target used by the /sendtax- 
get method. This method is called automatically 
when the button is destroyed. See GassTarget for 
more about targets and their uses. 

- /demo instance 

Create a sample abbreviated button and leave it 
on the stack. 

- /destroy - 

Turn off tracking if it is on, and destroy the but- 
ton. If the menu was passed in as an array and 
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/disable 



/enable 



/enabled? 



/graphic 



/location 



/minsize 



/move 



/new 



constructed on-the-fly by the button then it too 
will be destroyed. Otherwise it is up to the 
caller who passed the menu in to ensure its des- 
truction. 

- /disable - 

Stop responding to user actions; set the button's 
state to false, f>aint the button accordingly, and 
remove the tracking process when current 
requests are serviced. 

- /enable - 

Set the button's state to enabled, and display it 
accordingly with /PaintEnabledState. 

- /enabled? bool 

Return true if the button is currently enabled, 
false if it is disabled. When disabled, the button 
does not respond to user input. 

- /graphic obj 

Return the graphic object that represents the 
button on screen. 

- Aocation x y 

Return the location of the origin of the button 
relative to the CTM. 

- /minsize width height 

Return the smallest size the button can be and 
still appear intelligible. 

X y /move - 

Move the origin of the button to the specified 
location in the coordinates of the CTM. 

thing I graphic menu I array notify 
parentcanvas /new instance 
The arguments to /new specify: 

■ a parent canvas of the button. 
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■ a notification procedure or callback, 
which is executed whenever the SELECT 
button pressed and released over the can- 
vas. Remember that tracking for an 
OPEN LOOK button begii« when the 
mouse cursor enters the canvas and the 
SELECT button is pressed. Notification 
occurs when the SELECT button is 
released over the canvas. In order for the 
button to correctly function this callback 
must be null. While you may install you 
own button callback, the resulting 
behavior is likely to not be OpenLook 
compliant. The default callback for abbre- 
viate buttons implements the required 
OpenLook functionality by executing the 
default selection from the button menu 
when the SELECT button is released. 

■ a menu or menu specification. 

If an array is pass^ in it is assumed to be 
a specification for a menu that the button 
should instantiate automatically. It does 
this by sending /newdefault to 
ClassMenu: [menu specification] frame- 
buffer /newdefault ClassMenu send The 
result should be a a valid menu instance. 
Note that this interface does not support 
all the supported interfaces to /new in 
ClassMenu. The menu passed into /new 
(as an instance or a specification) is 
displayed whenever the MENU button is 
pressed over the button. If the supplied 
callback was null the default callback of 
the menu will be executed when the 
SELECT button is released over the but- 
ton. 
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/notifyproc 

/preferredsize 

/sendtarget 

/setarrow 

/setgraphic 
/set graphic 

/set notifyproc 
/set target 



■ a graphic or thing to be made into a 
graphic. 

If the object supplied is a thing or a non- 
terminal graphic, /CreateGraphic is called 
to make an instance of OPEN LOOKBut- 
tonGraphic from the argument 

- /notifyproc pcoc 

Return the button's current notify procedure. 

- /preferredsize width height 

Return the preferred or "ideal" sue for this but- 
ton, which by default is the miiumum si2e 
(/minsize). 

args /method /sendtarget results 
This method can be invoked within the 
notifyproc in order to send a message to some 
other iirstance. Many clients will not need to use 
this indirection. See ClassTarget for more details. 

/Left I /Right I /op I /Down /setarrow 
Abbreviated buttons display an arrow that indi- 
cates in which direction the menu will be 
displayed. This method will set the arrow direc- 
tion to one of four values and ensure that the 
menu is appropriately positioned when it is 
displayed. 

thing | graphic /setgraphic 

thing | graphic /setgraphic - 
Convert the argument to a graphic, if necessary, 
and store it as the button's graphic. Then, invali- 
date the button to require layout before repaint- 
ing. 

proc /setnotifyproc 

Set the notification procedure for the button, 
object /settarget 

Set the target used by the /sendtarget method. 
Note that the button itself does not typically 
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have a callback of its own. Instead, it usually 
relies upon the button to provide all its call- 
backs. Thus setting the target of the menu will 
also set the target of its menu. See ClassTarget 
for more about targets and their uses. 

/size - /size w h 

Return the width and height of the button rela- 
tive to the CTM. 

/target - /target object 

Returns the current target used by the /sendtar- 
get method. See ClassTarget for more about tar- 
gets and their uses. 

see also: 

OpenLookButton 



OpenLookAbbrButtonStack 

Subclass of OpenLookAbbrButton,OpenLookButtonStack 
Source file: OLbUtton.ps 

This class can be directly instantiated 

This class implements OPEN LOOK abbreviated button menus (previously 
called button stacks). 

see also: 

OpenLookAbbrButton, OpenLookButtonStack 



OpenLookBaseFrame 

Subclass of OpenLookFrame.ClassBaseFrame 
Source hie: OLframe.ps 
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This class can be directly instantiated 

Most applications will use an instance of this class as their main window on the 
screen. The methods documented below are those of interest to the user rather 
than the expert subclasser. 

An OPEN LOOK Base Frame is characterized by the following attributes: 

■ a header area on the top of the frame containing a header label and a 
menu button, 

■ an icon subframe, named /Icon, into which the frame closes 

■ a menu shared with the icon subframe 



■ an footer area at the bottom of the frame, containing messages on the left 
and/or right sices of the footer 

■ resize corners that permit the user to initiate resizing the frame by press- 
ing the SELECT button on the resize corners 

■ a single client canvas in the middle of the frame. 



Direct Methods 

/activate 



/active? 



/addsubframe 



/busy? 



/callnotify 



— /activate 

Activate event management for the frame and 
any subframes. 

— /active? bool 

Return true if event management has been 
activated on the frame (and subframes). 

neune frame /addsubframe — 

Add frame as a subframe by name and activate 
event management for it. 

— /busy? bool 

Return true if the frame is busy, which means 
the frame is temporarily not interested in input 
because it is processing a previous request. The 
busy state is indicated on screen with the /busy 
cursor, by default the hourglass. 

— /callnotify — 

Call the frame's notification procedure, which 
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/changed? 



/client 



/closesubframes 



/deactivate 



/demo 



/destroy 



/destroyfromuser 



/fitclient 



was stored by /setnotif5rproc. Commonly, the 
reason for notification is given to the frame 
using /setnotifyreason before calling the 
notification procedure. 

— /changed? bool 

Return the frame's /Changed? variable. This can 
be used by subclassers to indicate some change 
of state of interest to them. 

— /client cl lent I nul 1 

Return the frame's client canvas (/Client), or 
null if there is none. 

— /closesubframes — 

Close all open subframes and store their names 
internally; /opensubframes can later be used to 
open them. 

— /deactivate — 

Turn off event management for the frame and 
subframes. 

— /demo frame 

This is a demonstration method that will put on 
screen a simple OPEN LCX)K Base Frame. 

— /destroy — 

Destroy the frame and its subframes , deselect- 
ing them as necessary. 

— /destroyfromuser 

Destroy the frame, allowing the application to 
intervene if necessary (for example, to ask the 
user to save files). (Override this method to pro- 
vide special processing when destroying a 
frame. 

w h /fitclient w' h' 

Validate the frame if necessary, and then return 
the size the frame should be for its client to fit 
into it. 
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/flashframe 



/flipiconic 

/flipselected 

/flipzoom 

/focus? 

/footer 

/frameattribute 

/freeze 

/freezeall 



— /flashframe — 

Briefly repaint the frame with the focus indica- 
tion reversed; then repaint the frame as it was. 
This creates a flashing effect on screen. This 
method is used, for example, in the menu for 
OPEN LOOK popup frames to identify the 
owner of the popup frame. 

— /flipiconic — 

Toggle the frame's iconic state. If it is open, 
close it into an icon; if it is an icon, open it. 

sourceframe /flipselected — 

If the sourceframe is currently selected, deselect it 
and make this frame selected instead. 

— /flipzoom — 

Toggle the zoomed state of the frame; if it is 
enlarged (zoomed) make it normal size and vice 
versa. 

— /focus? bool 

Return true if the frame has the input focus. 

— /footer graphic 1 thing | nul 1 
graphic | thing | null 

Return the left and right footers of the frame. 
The argument returned for each footer can be 
either a graphic, a thing from which a graphic is 
made, or null. 

name /frameattribute bool 

Return the value of one of the frame attributes. 

See /new for a list of frame attributes. 

bool /freeze 

Freeze the frame when the argument is true, 
unfreeze when the argument is false. This 
makes the frame insensitive to events except 
damage and loss of focus or selection (/Dam- 
aged, /LoseFocus, /LoseSelection). 

bool /freezeall — 

This method freezes (true) or unfreezes (false) 
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/gravity 



/label 



/location 



/map 

/mapped? 



/menu 



/minsize 



all frames in the frame hierarchy of the reci- 
pient. If the recipient is a root frame, it and all 
subframes freeze or unfreeze, as dictated by the 
argument. If the recipient is a subframe, how- 
ever, its superframe(s) and their other descen- 
dant frames will freeze/unfreeze as well as the 
recipient and its subframes. 

— /gravity 

/UpperLef t | /UpperRight I /LowerLeft | /LowerRight 
Return the gravity variable for the frame. This 
is the side of the screen where the frame will 
tend to be placed when it is opened. 

— /label graphic I thing I null 

Return the label of the frame, which may be a 
graphic, a thing from which a graphic is made, 
or null. 

— /location x y 

Return the location of the origin of the frame in 
coordinates of the CTM. 

— /map — 

Map the frame and move it to the top. 

— /mapped? bool 

Return true if the frame is currently n\apped. 

— /menu menu I null 

Return the menu object associated with this 
frame as set by /setmenu and stored in the 
/CanvasMenu variable The menu is displayed 
whenever the MENU button is pressed with the 
pointer over the frame. Return null if there is 
no menu set. 

— /minsize minwidth minheight 
Return the minimum size for this frame based 
on the minumum size its main client (/Client) 
requires. 
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When subclassing, override this method if the 
calculations do not require the current canvas to 
be the frame. (If the calculations do require the 
frame as the current canvas, override /MinSize 
instead.) 

/move X y /move — 

Move the origin of the frame to the specified 
location in the coordinates of the CTM. 

/ new clientcanvas | null AVList 

parent canvas /new instance 

clientclass AVList parentcanvas /new 
instance 

[args clientclass] AVList 

parentcanvas /new instance 

This method creates a new frame, calling 
/newinit to perform initialization once the 
instance is created. The arguments to /new are: 

■ the parent canvas of the frame being 
created 

■ an attribute-value list (AVList), 
which is an array or dictionary of the 
attributes of the frame and their initial 
values. By default, an OPEN LOOK base 
frame has the /Close, /Footer, /Label, and 
/Reshape attributes set to true and /Pin set 
to false. To create an instancy with dif- 
ferent attribute values, the AV-list would 
be of the form [ attribute bool ], for exam- 
ple [ /Reshape false ]. The contents of the 
AV-list may be null, in which case, specify 
[]. A dictionary can also be used to 
specify the AV list, with the attribute 
names as keys. 

dictbegin /Footer false def /Reshape false def dictend 
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/newinit 



/notifyproc 



/notifyreason 



/notifyselected 



/open 



/opened? 



■ the dient, 

either the client canvas itself, or the dass 
from which to create an irwtance to be the 
client, or null. Specify the client as an 
argument if it has already been instan- 
tiated when the frame is created. Specify 
null if the dient is to be added at a later 
time. Specify a dass as the client argu- 
ment to have this method create an 
instance of that class as the client. If no 
additional processing is done on the dient 
between its creation and its being added 
to the frame, it is more efficient to spedfy 
a dass than an instance. Finally, if addi- 
tional arguments are required to create an 
instance, group them into an array, fol- 
lowing the clientclass. 

— /newinit 

Process the arguments to /new, and create an 
icon subframe. 

— /notifyproc pcoc 

Return the frame's notification procedure. 

— /notifyreason keyword 

Return the reason the frame's notification pro- 
cedure was called. This information was saved 
by sending /setnotifyreason to the frame before 
sending 

obj proc /notifyselected — 

This method is sent to a class to have proc sent 
to all selected instances of that dass. 

bool /open 

Open or close the frame and its subframes 
depending on the sense of the argument: open if 
true, close if false. 

— /opened? bool 

Return true if this frame is open. 
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/opensubframes 



/owner 



/pin 



/pinned? 



/place 



/popuphelp 



/preferredsize 



/ remove sub f r ame 



/reshape 



— /opensubframes — 

Open the subframes that had previously been 
closed and stored using /closesubframes. 

— /owner graphic I thing | null 
Returns the portion of the frame's label that 
indicates the frame's owner (superframe). 

— /pin — 

Pin the frame, if it is pinnable. This method 
invokes the pin notification procedure, /PinNo- 
tify. 

— /pinned? bool 

Returns true if the frame is currently pinned. 

— /place — 

This method computes a default location for the 
frame and places it there. If the frame has 
already been sized, it keeps that size. Other- 
wise, the frame assumes its preferred size. 

object /popuphelp — 

Create and pop up a help frame and display 
help about the specified object. If sent to a sub- 
frame, this message is pass^ on to the frame's 
superframe. The help frame is created as a sub- 
frame with the name /Help. If a help frame has 
already been created, it is reused. 

/preferredsize preferredwidth prefer- 
redheight 

Return the frame's preferred size, which is based 
on the preferred size of its main client, /Client 

name /removesubframe oldsubframe true 

name /removesubframe false 

Remove the name subframe, if it exists, returning 
the subframe and true. If the subframe does not 
exist, return false. Note that the frame is not 
deactivated by this method. 

X y w h /reshape — 

Reshape the frame to fit the given coordinates 
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/reshapefromuser 



/root frame 



/selected? 



/selectedframes 



/sendroot frame 



/sendselected 



/sendsubframe 



/sendsuperframe 



and invalidate the frame. This forces the frame 
and its clients to do layout before repainting. 

— /reshapefromuser — 

This method is used by an application to initiate 
user interaction to reshape the frame. First, the 
cursor will change, by default to a crosshair. 
Next, the NeWS process will block until the user 
drags the mouse to sweep out a bounding box. 
Then, the frame will be resized to fit the bound- 
ing box. 

— /rootframe frame 

Returns the root frame of this frame. A root 
frame is a frame that has no superframe. 

— /selected? bool 

Returns true if this frame is the selection target. 

— /selectedframes [selectedframes] 

This method is sent to a subclass of GassFrame 
and returns an array of its instances that are 
selected. 

<methodargs> /method /sendrootframe — 
Send method together with the supplied argu- 
ments to the frame's root frame. 

/method I array /sendselected 
This method is sent to a subclass of GassFrame 
to send the arguments to each selected instance 
of that class. The aiguments may be a method 
name or an array of the form [arg aig ... 
/method]. The array may be executable or not. 

args . . . /method subframe /sendsubframe 

Send method and args to subframe. If the sub- 
frame does not exist, an error occurs. 

methodargs /method /sendsuperframe — 
Send /method and methodargs to the frame's super 
frame. 
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/setbusy 
/set changed 

/setclient 

/setfocus 

/setfooter 

/setframeattribute 



/setgravity 



bool /setbusy — 

Mark the frame as busy (true) or not busy 
(false). 

bool /setchanged — 

Mark the frame as "changed". This facility is 
provided for subclassers or applictions that need 
to maintain additional state for their frames. 

newclient /setclient oldclient (null 
Set the frame's client to the specified canvas. 

Return the previous client, or null if there was 
none, or null if there was none. 

bool /setfocus — 

Give the frame the input focus. 

Lgraphic | Lthing | null 
Rgr aphic | Rthing | nul 1 /setfooter 
Set the objects that define the right and left 
footer elements. Each element can be null, a 
graphic, or a thing from which a graphic is 
made. Null does not change the existing ele- 
ment, if there is one. To remove an element, set 
it to nullstring. 

name bool /setframeattribute 
array /setframeattribute — 
diet /setframeattribute — 

This method is used to dynamically change 
frame attributes, possibly resulting in the frame 
requiring validation afterwards. The arguments 
are of the form attribute bool If there are several 
argument pairs, they may be enclosed in an 
array: 

[ attl bool attl bool2 ] 

Alternatively, the argument-value pairs may be 
enclosed in a dictionary: 

dietbegin attl booll def attl booll del dictend 

/UpperLeft | /UpperRight | /LowerLeft | /LowerRighI 
/setgravity — 

Set the frame's gravity, which is the side of the 



Interface Reference 



11-99 




Interface Reference 



/seticon 



/ set icongra vi t y 



/seticonlabel 



/setlabel 



/setnotifyproc 



/setnotifyreason 



/setowner 



/setproperties 



screen the frame will tend toward when first 
opened. 

{paint} I [array] I canvas! (string) j/naine /seticon 

Create the frame's icon as specified: 

{paint} paint procedure of the icon canvas 

[args.xlass] an instance is created and used for the icon 
canvas use this canvas as the icon image 

(string) use the string as the icon image 
Iname get character from iconfont 

/Left I /Right j /Top j /Bottom /seticongravity 

Set the gravity variable for the frame's icon. 

(string) /seticonlabel — 

Set the label for the frame's icon, removing the 
old label if there was one. Use nullgraphic for 
no label. 

graphic I thing I null /setlabel — 

Store a new value for the frame's label: a 
graphic, a thing from which a graphic is made, 
or null. 

proc /setnotifyproc — 

Set the notification procedure for the frame. 

This procedure is c^led with the frame itself on 
the operand stack whenever a user action 
changes the state of the frame. 

keyword /setnotifyreason — 

This method is used to supply a reason for cal- 
ling the notification procedure, just before cal- 
ling it. 

graphic I thing I null /setowner — 

Set the portion of the frame's label that indicates 
the frame's owner (superframe). 

— /setproperties — 

If a properties subframe already exists for this 
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/size 

/subframe 

/subframe? 

/subframes 

/super frame 
/toback 
/tofront 
/unfitclient 



/unmap 

/unpin 



frame, open it. Otherwise, create one and open 
it. The properties frame is shared. 

— /size w h 

Return the current width and height of the 
frame. 

name /subframe frame true 

name /subframe false 

Return the named subframe and true if the sub- 

frame exists, otherwise return false. This can be 

used to retrieve the icon (/Icon), for example. 

name /subframe? bool 
Returns true if subframe name exists. 

— /subframes diet 

Return a dictionary whose keys are the names of 
subframes of this frame, and whose values are 
the subframe instances. 

— /superframe frame 

Return this frame's superframe or this frame 
itself if it has no superframe. 

— /toback — 

Move the frame and its subframes to the bottom 
(back) on the screen. 

— /tofront — 

Move the frame and its subframes to the top 
(front) on the screen. 

w h /unfitclient w' h' 

Return the size the frame's client should be to fit 
into the frame. This is the opposite of /fitclient, 
which says how big the frame should be to hold 
the client. Note that, if necessary, the frame is 
validated first. 

— /unmap — 

Unmap the frame and give up being selected. 

— /unpin — 

If the frame is pinned, unpin it. 
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/zoom bool /zoom 

Expand the frame to full size if the argument is 
true, or revert to normal size if false. 

/zoomed? — /zoomed? bool 

Return true if the frame is currently full size. 



see also: 

OpenLookFrame, ClassBaseFrame 



OpenLookButton 

Subclass of ClassButton 
Source file: OLbutton.ps 

This class can be directly instantiated. 

This class implements OpenLook buttons. It is also the main superclass for but- 
ton stacks and abbreviated buttons. 



Direct Methods 

/callnotify 



/cleartarget 



/default? 



- /callnotify - 

Call the button's notify procedure uncondition- 
ally, with the button itself on the operand stack. 

object I null /cleartaiget 
Selectively dear the target. If null is given, the 
target is cleared. If object is given, the target is 
cleared only if the object and the traget are the 
same. This ensures that the target cannot be 
incorrectly cleared. 

Note that the /destroy method of any object 
pointed to by a target should clear the target as 
part of destroying the object. 

- /default? bool 

Return true if this button has been designated 
the default (for a menu, for example) 
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/demo 



/destroy 



/disable 



/enable 



/enabled? 



/graphic 



/location 



/minsize 



/move 



/new 



- /demo Instance 

Show a sample OPEN LOOK button, whose call- 
back writes to the console. 

- /destroy - 

Turn off tracking if it is on, and destroy the but- 
ton. 

- /disable - 

Stop responding to user actions; set the button's 
state to false, paint the button accordingly, and 
remove the tracking process when current 
requests are serviced. 

- /enable - 

Set the button's state to enabled, and display it 
accordingly with /FaintEnabledState. 

- /enabled? bool 

Return true if the button is currently enabled, 
false if it is disabled. When disabl^, the button 
does not respond to user input. 

- /graphic obj 

Return the graphic object that represents the 
button on screen. 

- /location x y 

Return the location of the origin of the button 
relative to the CTM. 

- /minsize w h 

Return the smallest size the button can be and 
still appear intelligible. 

X y /move 

Move the origin of the button to the specified 
IcKation in the coordinates of the CTM. 

thing I graphic notifyproc 
parentcanvas /new instance 
The arguments to /new specify: 
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/notifyproc 

/preferredsize 

/sendtarget 



■ a parent canvas of the button. 

■ a notification procedure or callback, 
which is executed whenever the SELECT 
button on the mouse is released over the 
button. Remember that tracking for an 
OPEN LOOK button begins when the 
mouse cursor enters the button and the 
SELECT button is pressed. Notification 
occurs when the SELECT button is 
released over the button. 

■ a graphic or thing to be made into a 
graphic. 

If the object supplied is a thing or a non- 
terminal graphic, /CreateGraphic is called 
to make an instance of OpenLookButton- 
Craphic from the argument. 

- /notifyproc proc 

Return the button's current notify procedure. 

- /preferredsize width height 

Return the preferred or "ideal" size for this 
button, which by default is the minimum size 
(/minsize). 

args /method /sendtarget results 
Send the method and arguments to the target 
object. Any button can have a "target” which 
you can set, get, and send to. For example, if 
you have a button that needs to send a message 
to object foo when the button's callback is exe- 
cuted: 

^ (Hello) {/foo-method /sendtarget 3 -1 roll send} 
framebuffer /new OpenLookButton send def 

foo /settarget b send 

When the button is pressed, foo-method will be 
sent to foo. You can change the target at any 
time if you want to make your button send to 
different objects at different times. 
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/setdefault 



/setgraphic 



/setnotifyproc 



/settarget 



/size 



/target 



Class Variables 

/Default 



An error results from sending anything to a null 
target 

bool /setdefault - 

Mark this button as a default. Currently this 
only affects the graphical look of the button by 
drawing an extra "default ring" drawn in it. 

thing | graphic /setgraphic 

Convert the argument to a graphic, if necessary, 

and store it as the button's graphic. Then, 

invalidate the button to require layout before 

repainting. 

proc /setnotifyproc - 

Set the button's notify procedure, overwriting 

the previous one. 

object /settarget 

Set the target object, overwriting the previous 
target, if there was one. 

- /size w h 

Return the width and height of the button in the 
coordinates of the CTM. 

- /taiget object 

Return the target of this button. If left unset, 
this value defaults to the button itself. See 
ClassTarget for a more complete description of 
targets and their usage in controls and menus. 



An OPEN LOOK button has an additional 
binary state named /Default, which is not con- 
nected with its enabled /disabled state or its 
on/off value. It is used, for example, in OPEN 
LOOK button menus to designate one button as 
the default selection for the menu. The button 
designated as the default is painted with an ring 
inside its outline. The default value of this vari- 
able is false. 
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see also: 

ClassButton 



OpenLookButtonStack 

Subclass of OpenLookButton 
Source file: OLbutton.ps 

This class can be directly instantiated. 

This class implements OpenLook Button Stacks (now called Button Menus in 
OPEN LOOK), as well as being the primary superclass for OpenLook Abbrevi- 
ated Button Stacks. 



Direct Methods 

/demo 



/destroy 



/disable 



/enable 



/enabled? 



- /demo instance 

Create a demonstration button stack on the 
framebuffer. This method will only be available 
if /IncludeDemos? was true at the time this 
class was read in. 

- /destroy - 

Turn off tracking if it is on, and destroy the but- 
ton. If the menu was passed in as an array and 
constructed on-the-fly by the button then it too 
will be destroyed. Otherwise it is up to the 
caller who passed the menu in to ensure its des- 
truction. 

- /disable 

Stop responding to user actions; set the button's 
state to false, paint the button accordingly, and 
remove the tracking process when current 
requests are servic^. 

- /enable - 

Set the button's state to enabled, and display it 
accordingly with /FaintEnabledState. 

- /enabled? bool 

Return true if the button is currently enabled. 
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/graphic 



/location 



/menu 



/menubelow 



/menubelow? 



/move 



false if it is disabled. When disabled, the button 
does not respond to user input. When enabled 
it will respond to both the SELECT and MENU 
mouse buttons. 

- /graphic obj 

Return the graphic object that represents the 
button on screen. 

- /location x y 

Return the location of the origin of the button 
relative to the CTM. 

- /menu menu I null 

Return the menu object associated with this but- 
ton as set by /new or /setmenu. The menu is 
displayed whenever the MENU button is 
pressed with the pointer over the canvas. The 
menu default is executed if the button callback 
is null and SELECT button is pressed and 
released over the canvas. Return null if there is 
no menu set. 

bool /menubelow - 

This method is used to determine on which side 
of the button the menu will pop-up on. By 
default the menu is displayed below the button 
stack, passing false to this method would cause 
the menu to pop-up to the right of the button. 
The functionality to position the menu to the 
right of the button has not yet been imple- 
mented so only true should be passed to this 
method for now. 

- /menubelow? bool 

Returns true of the menu for this button will be 
displayed below the button. Othertwise the 
menu will come up to the right of the button. 

X y /move 

Move the origin of the button to the specified 
location in the coordinates of the CTM. 



Interface Reference 



11-107 




Interface Reference 



/new thing menu I array notifyproc 

parentcanvas /new Instance 
The arguments to /new specify: 

■ a parent canvas of the button. 

■ a notification procedure or callback, 
which is executed whenever the SELECT 
button pressed and released over the can- 
vas. Remember that tracking for an 
OPEN LOOK button begins when the 
mouse cursor enters the canvas and the 
SELECT button is pressed. Notification 
occurs when the SELECT button is 
released over the canvas. In order for the 
button to correctly function this callback 
must be null. While you may install you 
own button callback, the resulting 
behavior is likely to not be OPEN LOOK 
compliant. The default callback for abbre- 
viate button stacks implements the 
required OpenLook functionality by exe- 
cuting the default selection from the but- 
ton menu when the SELECT button is 
released. 

■ a menu or menu specification. 

If an array is pass^ in it is assumed to be 
a specification for a menu that the button 
should instantiate automatically. It does 
this by sending /newdefault to 
ClassMenu: [menu specification] frame- 
buffer /newdefault ClassMenu send The 
result should be a a valid menu instance. 
Note that this interface does not support 
all the supported interfaces to /new in 
ClassMenu. The menu passed into /new 
(as an instance or a specification) is 
displayed whenever the MENU button is 
pressed over the button. If the supplied 
callback was null the default callback of 
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/newinit 



/preferredsize 



/setgraphic 



/setmenu 



the menu will be executed when the 
SELECT button is released over the but- 
ton. 

■ a graphic or thing to be made into a 
graphic. 

If the object supplied is a thing or a non- 
tenninal graphic, /CreateGraphic is called 
to make an instance of OPEN LOOK But- 
tonGraphic from the argument. 

thing menu | array notify /newinit 
This method is called by /new and is responsible 
for consuming the callback, the menu 
speicification, and the thing or graphic. This is 
primarily a method used by subclassers; users 
should not call this method directly. 

- /preferredsize width height 
Return the preferred or "ideal" size for this but- 
ton, which by default is the minimum size 
(/minsize). 

thing | graphic /setgraphic 
Convert the argument to a graphic, if necessary, 
and store it as the button's graphic. Then, invali- 
date the button to require layout before repaint- 
ing. 

menu 1 array /setmenu 

Install or remove a popup menu for this canvas. 
The menu is activated by the user pressing the 
MENU button when the pointer is over the but- 
ton. The menu defauilt is activated by by the 
user pressing and releasing the SELECT button 
when the pointer is over the button. If an array 
is passed in it is assumed to be a specification 
for a menu that the button should instantiate 
automatically. It does this by sending /newde- 
fault to ClassMenu: 
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[menu specification] framebufiw /newdefault ClassMenu send 

The result should be a a valid menu instance. 

Note that this interface does not support all the 
supported interfaces to /new in ClassMenu. 

/size - /size w h 

Return the width and height of the button rela- 
tive to the CTM. 



Subclass Methods 

/DisplayDefault - /DisplayDefault 

This method displays the default menu selection 
in place of the button graphic. Typically this 
method is called automatically when the user 
presses the SELECT mouse button over an 
active, enabled button stack. 

/UnDisplayDefault - /UnDisplayDefault 

This method displays the button graphic in 
place of the default nnenu selection . 



see also: 

OpenLookButton 



OpenLookCheckBox 

Subclass of OpenLookXSettingControl 
Source file: OLxctrl.ps 

This class can be directly instantiated. 

This class implements OPEN LOOK check boxes, a nonexclusive setting used in 
lists of yes-no choices. The implementation of this class is subject to change in 
the future. 

see also: 

OpenLookXSettingControl 



11-110 



tNt Technical Reference Manual 




Interface Reference 



OpenLookChoggle 

Subclass of OpenLookXSetting 
Source file: OLxset.ps 

This class can be directly instantiated. 

This classs implements OpenLook “choggles", which is a set of items, of which 
zero or one is selected at any time. It can be thought of as an exclusive setting 
that can be turned off altogether. 

see also: 

OpenLookXSetting 



OpenLookCommandFrame 

Subclass of OpenLookFrame,ClassCommandFrame 
Source file: OLframe.ps 

This class can be directly instantiated. 

This class is OpenLookBaseFrame with the following differences; command 
frames: 

■ have a pin 

■ do not have a footer 

■ cannot be closed into an icon (have no "iconic" state) 

■ cannot be quit from or closed into an icon (pressing SELECT over the 
close box or selecting "Dismiss" from their menu simply uiunaps them 
from the screen.) 

see also: 

OpenLookBaseFrame 
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OpenLookFrame 

Subclass of ClassFrame 
Source file: OLframe.ps 

This class should be subclassed rather than directly instantiated. 

This class is used to "mix-in" OpenLook features into frame subclasses. For 
example, it is mixed in with ClassBaseFrame to produce OpenLookBaseFrame. 
Likewise, it is mixed in to produce the other OPEN LOOK frame types: com- 
mand, icon, help, notice, and property. 



OpenLookHeipFrame 

Subclass of OpenLookFrame, ClassHelpFrame 
Source file: OLframe.ps 

This class can be directly instantiated. 

This class is OpenLookBaseFrame with the following differences; Help frames: 

■ have a pin 

■ do not have a footer 

■ do not have a resize tab. 

■ cannot be quit or closed into an icon (pressing SELECT over the close box 
or selecting 'Dismiss" from their menu simply unmaps them from the 
screen). 

see also: 

OpenLookBaseFrame 

OpenLookHorizontalScrollbar 

Subclass of ClassScrollbar.ClassBag 
Source file: OLsbar.ps 
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This class can be directly instantiated 

The only differences between this class and OpenLookVerticalScrollbar are: 

1 . the vertical scrollbar has an origin in the upper left corner, whereas Open- 
LookHorizontalScrollbar uses the standard lower left origin. 

2. The nnenu associated with the vertical scrollbar has "Here to top", 
whereas OpenLookHorizontalScrollbar has "Here to left". 

see also: 

OpenLookVerticalScrollbar, ClassScrollbar, QassBag 



OpenLookHorizontalSlider 

Subclass of CiassDialControl 
Source file: OLslider.ps 

This class can be directly instantiated 

An OpenLookHorizontalfflider is an analog control. Users can pick up and drag 
the drag box, or click to me left or right of it. This class has the same interface 
as OpenLookVerticalSlider. 

Direct Methods 

/destroy 
/minsize 



/motion 



/new 



— /destroy — 

Etestroys the slider drag box and then destroys 
itself. 

— /minsize minwidth minheight 
Returns the minimum width and height of the 
slider. This leaves enough room for the drag box 
only. 

— /motion motion 

Returns the current motion, as set by /SetMo- 
tion. The motion for sliders is either /Absolute, 
when the drag box is dragged, or /Line, when 
the mouse is clicked outside the drag box. 

notifyproc parentcanvas /new instance 
Creates and returns an instance of a slider. The 
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/newinit 



/setdelta 



/setnormalization 



/setnotifyproc 



/setposition 



/set range 



parentcanvas is consumed by /newobject 
/newinit consumes the notif^roc. 

notifyproc /newinit 

Initializes the slider. This does the normal con- 
trol initialization and then creates the slider drag 
box. 

name value /setdelta 

This sets the specified delta to the value. The 
only delta that is used by sliders is /Line. 

number /setnormalization — 

The normalization defines the granularity of the 
values for the slider. 

proc /setnotifyproc 

Takes the argument proc and makes it the call- 
back for the slider. The callback will be called 
by /checknotify with the slider itself on the 
stack. 

event /setposition — 

Expects an X/Y pair or an event (which it then 
turns into an X/Y pair) and sets the value of the 
slider according to that specified position. 

min max /setrange — 

Sets the range displayed by the slider. 



Subclass Methods 

/ClientDown 



/ClientDrag 



event /ClientDown 

This method is called when the user mouses 
down over the slider. This sets the slider 
motion according to where the mouse hit 
occurred. If the mouse hit occurs inside the 
slider drag box, the motion is /Absolute, other- 
wise it is /Line. 

event /ClientDrag — 

This drags the drag box if the motion is /Abso- 
lute, that is, if the last /ClientDown was inside 
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/ClientUp 



/PaintCable 



/PaintCanvas 



/SetMotion 



see also: 

ClassDialControl 



the drag box. This calls /checknotify. If you 
don't want notification on every drag event, 
override /CallNotify? to return false when the 
current motion is /Absolute. 

event /ClientUp — 

This method is called when the user lets go of 
the mouse button that caused /ClientDown to 
be called. If the motion was /Line then the drag 
box is moved now. If the motion was /Absolute 
the drag box is already positioned, /checknotify 
is called in either case. 

— /PaintCable — 

Paints the slider cable. 

— /PaintCanvas — 

Paints the slider with the current value. 

event /SetMotion 

Sets the motion of the slider to be /Absolute 
when the drag box is dragged, and to /Line 
when the mouse is clicked outside the drag box 
(but otherwise inside the slider). 



OpenLookIconFrame 

Subclass of OpenLookFrame.ClassIconFrame 
Source file: OLframe.ps 

This class can be directly instantiated. 

An OpenLookIconFrame is automatically created to accompany every Open- 
LookBaseFrame; it is a full blown frame that by default has no resize corners, 
footer, or pin. 
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see also: 

OpenLookBaseFrame 



OpenLookMenu 

Subclass of ClassMenu 
Source file; OLmenu.ps 

This class can be directly instantiated 

This class innplements pop-up and stay-up piimable OpenLook ntenus. It is 
meant to be directly instantiated. Also note that QassOnvas 
provides code to watch for the menu button, and show any menu registered 
via /setmenu. 



Direct Methods 

/change 



/cleartarget 



/default 



/delete 



location thing | graphic 

genproc I sublist I null procinull /change 

Replace the menu item at the specified location. 
The arguments other than location are the same 
as for /new. This method invalidates the menu, 
so it must be repainted after the change. 

object I null /cleartaiget - 

Clear the menu target. If an object is supplied 

as a parameter, the target will be cleared only if 

the current target matches the parameter. 

ClassTarget for more about targets and their 

uses. 

- /default index 

Return the index of the default menu item, 
location /delete 

Delete the menu item at the specified location. 
This invalidates the menu, so it should be 
repainted after the change. 
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/demo 



/destroy 



/dlsableltem 



/doaction 



/dode fault 



/enableitem 



/graphic 



/insert 



- /demo canvas 

Invoke a demonstration menu. The purpose of 
this menu is to show how to use some com- 
monly used methods of Open Look menus. 

- /destroy - 

Destroy the menu and its pinned copy if 
present. 

index /disableitem - 

Disables a menu item rendering it unselectable. 
The item's color is changed to DisabledColor to 
indicate its disabled state. 

- /doaction - 

Execute the action associated with the currently 
selected menu item, i.e. the item whose index 
matches the menu's current value. If the item 
has a notify proc, it is called. If the item has a 
submenu, the notify proc of the submenu's 
default item is called. 

- /dodefault - 

Execute the action associated with the default 
menu item. The menu's value is set to its 
default, and /doaction is called. This method 
does nothing if the menu has no default or if the 
default item is disabled. 

index /enableitem - 

Enable the menu item at the specified location. 

location /graphic graphic 

Return the graphic associated with the menu 

item at the specified location. 

location graphic procedure! menu | null 
proc /insert - 

Insert a new menu item at the specified location. 
Except for location, the arguments are the same 
as for /new. This method invalidates the menu, 
so it must be repainted after the change. 
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/itemcount 

/itemenabled? 

/label 

/layout 

/layout style 

/maxlocation 

/new 

/newinit 

/nonxvalue 



- /itemcount integer 

Return the number of items in the menu. 

location /itemenabled? bool 

Return true if the item at the specified location 

is enabled. 

- /label graphic i null 

Return the graphic associated with the menu's 
label. 

- /layout width height 

Arrange the menu label, pin and items accord- 
ing to the layout style specified by /setlay- 
outstyle. Returns the size of the menu. 

- /layoutstyle RowMajor? Rows | null 
Columns I null 

Return the layout style for the menu. See class 
RowColumnlayout. 

- /maxlocation location 

The largest location of the menu. Menu locations 
are specified as small integers ranging from 
0...n-l, where n is the total number of control 
items in the menu. 

[thing | graphic genproc | sublist | null 
proc I null . . . ] parent /new inst 
thing I graphic . . . ] genproc | null proc | null 
parent /new inst 

Create a menu. See the OpenLook Menu section 
for a description of the parameters. 

[thing | graphic genproc | sublist | null 
proc I null . . . ] /newinit 
[ thing | graphic . . . ] genproc | null 
proc I null /newinit 

- /nonxvalue [nonxvalues. . .] |null 

Return an array of nonexclusive menu items 
currently selected. Returns an empty array if no 
nonexclusive items are selected. Returns null if 
the menu contains no nonexclusive items. 
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/notifyproc 

/owner 

/pin 

/pinnable? 

/pinned? 

/popdown 

/popup 

/ sear chgraphic 



/searchthing 



location /notifyproc procedure {null 
Return the notify proc associated with a particu- 
lar menu item. 

- /owner string I null 

Return the owner string or graphic associated 
with the menu. 

- /pin - 

Pin a pinnable menu. 

- /pinnable? bool 

Return true if the menu is pinnable. 

- /pinned? bool 

Return truetrue if the menu is pinned. 

- /popdown - 

Remove the menu and any submenus from the 
screen. 

X y /popup 

Pop up Ae menu at the specified location, rela- 
tive to the CTM. The menu is activated. 

graphic /searchgraphic index true 

graphic /searchgraphic false 

graphic start loc /searchgraphic index 

true 

graphic start loc /searchgraphic false 

Search for the menu item having the given 
graphic. If a starting location is given, begin the 
search at that item. The search ends with the 
last menu item and does not wrap around. 

thing /searchthing index true 

thing /searchthing false 

thing start loc /searchthing index true 

thing startloc /searchthing false 

Search for the menu item having the given 
thing. If a starting location is given, begin the 
search at that item. The search ends with the 
last menu item and does not wrap around. 
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/sendtarget 

/setdefault 

/setgraphic 

/setlabel 

/setlayoutstyle 

/setnotifyproc 



/setowner 

/setpinnable 



args /method /sendtaiget results 
This method can be invoked within the 
notifyproc in order to send a message to some 
other instance. See ClassTarget for more details. 

Index /setdefault 

Set the default menu item. 

location thing I graphic /setgraphic - 
Set or change the graphic at the specified menu 
item location. 

nul 1 1 graphic | thing /setlabel 

Set or change the label at the top of the menu. 

RowMajor? Rows I null 

Columns I null /setlayoutstyle 

Change the layout style of the menu. See class 

RowColumnLayout. 

location procedure | null /setnotifyproc 
Change the notification procedure (callback) 
associated with a menu item. Note that if you 
specify a single notify proc when creating a 
menu, the notify proc is duplicated for each 
menu item. You may therefore change indivi- 
dual menu item callbacks without affecting oth- 
ers. Also, to change the callbacks for all menu 
items, you must call /setnotifyproc for each item 
in the menu. 

string | null | proc /setowner 
Set the owner field of a menu. When the menu 
is pinned, the owner field is shown to the left of 
the menu label. This helps users distinguish oth- 
erwise identical coexisting pinned menus. The 
owner is a string that may either be specified 
explicitly or may be returned by a piece of exe- 
cutable code (the proc). 

bool /setpinnable - 

Set the menu to be pinnable. By default a menu 
does not have a pin. 
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/setsublist 



/settarget 

/setvalue 

/showat 



/sublist 

/sublist? 

/target 

/value 



/valuething 



location genproc | snblist | null /setsublist 

Set the submenu associated with a menu item. 
The submenu may either be a menu instance or 
may be a procedure that returns a menu 
instance. 

object /settaiget - 
Set the target used by the /sendtarget 
method. See QassTarget for more about targets 
and their uses. 

index! null /setvalue - 
Set the current value of the menu. 

X y /showat - 
event /showat - 

Draw the menu at specified x and y locations 
and start a tracking manager for the menu. 
Showat has the same effect as pressing the menu 
button. 

location /sublist sublist {null 

Get the submenu associated with a menu item. 

Returns null if there is no submenu for the item. 

location /sublist? boolean 

Return true if the specified menu item has an 

associated submenu. 

- /taiget object 

Return the target object. 

- /value index 

Return the last selected menu item. The value is 
an integer from 0 to one less than the number of 
items in the menu. The value will be null if the 
menu is displayed, but no item is selected. 

- /valuething thing j null 

Returns the thing associated with the current 
value. 
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/xvalue - /xvalue Index I null 

Return the selected exclusive menu item. 
Returns null if the menu contains no exclusive 
menu items or if none are selected. 



OpenLookNonXSetting 

Subclass of OpenLookXSettIng 
Source file: OLxset.ps 

This class can be directly instantiated. 

This class implements an Open Look nonexclusive setting group. The group 
displays multiple setting items on a single canvas. The group acts like a control 
in that it has a single value, although since more than one %tting item may be 
selected at once, the value is an array of all selected values. Each item has an 
associated notify procedure that is cdled when the item is selected or 
deselected. 

Direct Methods 

/adjust location /adjust 

Toggle the value of the item indicated by loca- 
tion. If location is greater than the number of 
items, toggle the last one. 

/border - /border nuniber 

Return the size of the border around the entire 
group of settings. 

/change location thing {graphic 

genproc|sublist|null prod null /change 

Change the setting item at the specified location. 
The parameters, other than location, are the 
same as for /new. 

/cleartarget object I null /cleartaiget - 

Clear the control's target object. If an object is 
supplied as a parameter, the target will be 
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/clientcount 

/clientlist 

/delete 

/demo 

/destroy 

/disableitem 

/doaction 

/enableitem 

/gaps 

/graphic 

/insert 



/invalidate 



cleared only if the current target matches the 
parameter. See ClassTarget for more about tar- 
gets and their uses. 

- /clientcount int 

Return the number of items in the setting. 

- /clientlist array 

Return an array of dictionaries, one per item in 
the control group. 

location /delete - 

Etelete the specified setting item from the group. 

- /demo instance 

Create a demonstration nonexclusive setting on 
the framebuffer. 

- /destroy - 

Destroy the exclusive setting control. 

index /disableitem - 

Disable the item at the specified location. 

- /doaction 

index /enableitem - 

Enable the item at the specified location. 

- /gaps horizontalgap verticalgap 
Return the amount of space between the setting 
items. 

location /graphic graphic 

Return the graphic for the specified setting item. 

location thing | graphic 
genproc I sublist I null prod null /insert 
Insert a new setting item at the specified posi- 
tion in the group. The parameters, other than 
location, are the same as for /new. 

- /invalidate - 

Invalidate the setting and all of its item graph- 
ics. 
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/iteracount 

/iteraenabled? 

/layout 

/layout style 

/location 

/raaxlocation 

/rainsize 

/move 

/new 

/notifyproc 

/preferredslze 



- /itemcount integer 

Return the number of items in the setting group. 

location /itemenabled? bool 
Return true if the specified item is enabled. 

- /layout - 

Lay out the setting items. This sizes and places 
the items according to the layout style for the 
setting. 

- /layoutstyle RowMajor? Rows I null 
Columns I null 

Return the layout style for the menu. See 
RojvColumnLayout. 

- /location x y 

Return the location of the setting canvas. 

- /maxlocation location 

The location of the last item in the control. Item 
locations range from 0 to /maxlocation. /maxlo- 
cation is one less than /itemcount 

- /minsize minwidth minheight 
Return the minimum size of the setting. 

X y /move 

Move the setting's canvas to the specified loca- 
tion, relative to the CTM. 

[thing I graphic prod null ...] 

canvas /new instance 

Create a nonexclusive setting group. Refer to 

the introductory section OPEN LOOK Settings 

for the details of the arguments. 



location /notifyproc procedure | null 
Return the notify proc for the item at the 
specified location. 

- /prefeiredsize width height 

Return the preferred size of the setting group. 
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/reshape 



/ sear chgraphlc 



/searchthing 



/sendtarget 



/setborder 



/set gaps 



/set graphic 



X y w h /reshape - 

Reshape the setting group's canvas, and invali- 
date the setting group. 

graphic /seaichgraphic index true 

graphic /seaichgraphic false 

graphic startloc /seaichgraphic Index 

true 

graphic startloc /seaichgraphic false 

^arch for the setting item having the given 
graphic. If a starting location is given, begin the 
search at that item. The search ends with the 
last menu item and does not wrap around. 

thing /seaidithing Index true 

thing /searchthing false 

thing startloc /seardithing Index true 

thing startloc /searchthing false 

Search for the setting item having the given 
thing in its graphic. If a starting location is 
given, begin the search at that item. The search 
ends with the last menu item and does not wrap 
around. 

args /method /sendtarget results 
Send a message to the target object. Typically 
used in the control's notify proc. See QassTarget 
for more details. 

number /setborder 

Set the size of the border around the entire 
group of settings. 

horlzontalgap | null 

vertlcalgaplnull /setgaps 

Change the amount of space between the setting 

items. A null parameter leaves that value 

unchanged. 

location thing I graphic /setgiaphic - 
Change the graphic for the specific setting 
item. 
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/setlayoutstyle 



/setnotifyproc 



/settarget 



/setvalue 



/target 



/value 



/valuething 



RowMajor? Rows I null 
Columns I null /setlayoutstyle - 
Change the layout style of the menu. See 
RowColumnLayout for a more complete descrip- 
tion of the arguments. 

location procedure ! null /setnotifyproc 
Change the notification procedure (callback) 
associated with a setting item. Note that if you 
specify a single notify proc when creating the 
setting group, the notify proc is duplicated for 
each item. You may therefore change individual 
item callbacks without affecting others. Also, to 
change the callbacks for all items, you must call 
/setnotifyproc for each item. 

object /settarget - 

Set the target used by the /sendtarget method. 
See CkssTarget for more detail about targets and 
their uses. 

index I [index index ...] /setvalue 
Change the value of the setting. If a single 
index is supplied, that item is selected and all 
other items are deselected. If an array is sup- 
plied, the items specified by the indices in the 
array are selected. 

- /target object 

Return the target object. See QassTarget. 

- /value index 

Return an array of indices corresponding to 
selected items. If no items are selected, an 
empty array is returned. 

- /valuething [things] 

Return the thing of the graphic of the selected 
item, or null. 
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see also: 

OpenLookXSetting, RowColumnLayout, ClassTarget 

OpenLookNoticeFrame 

Subclass of OpenLookFrame.ClassNoticeFrame 

Source file: OLframe.ps 

This class can be directly instantiated. 

This class is OpenLookBaseFrame with the following differences; command 
frames: 

■ have a pin 

■ do not have a footer 

■ cannot be closed into an icon (have no "iconic” state) 

■ resist being frozen. 

see also: 

OpenLookBaseFrame 



OpenLookNumeric 

Subclass of ClassControl,ClassBag 
Source file: OLnumctrl.ps 

This class can be directly instantiated 

An Open Look numeric control is a ClassBag that contains an OpenLook- 
TextControl plus a pair of buttons that increment and decrement the numeric 
value displayed in the text control. The numeric value may be either integer or 
real. Many methods that pertain to the text control, such as /settextparams, are 
implemented also in OpenLookNumeric, which simply passes the messages to 
the underlying text control. 



Interface Reference 



11-127 




Interface Reference 



Direct Methods 

/callnotify 



/checknotify 



/cleartarget 



/decrement 



/demo 



/destroy 



/disable 



- /callnotify - 

Call the client's notifyproc, and remember the 
current value for use by /checknotify. 

object 1 null /checknotify 
Call the client's notifyproc only if the current 
value differs from the value as of the last call to 
/callnotify. This method is called automatically 
whenever the text control calls its notifyproc, 
i.e., when RETURN is typed or the control loses 
the input focus after the text has been changed. 
(Note that it is possible for the text to change 
without changing the numeric value, e.g., by 
adding zeroes at the front.) 

object I null /cleartaiget 

Selectively clear the target used by the /sendtar- 

get meth^. This method is called automatically 

when the numeric control is destroyed. See 

ClassTarget for more about targets and their 

uses. 

- /decrement 

Decrement the value by one unit. The unit 
defaults to 1, but can be changed by the /setin- 
crement method. The decrement button sends a 
/decrement message. 

- /demo instance 

Create a sample numeric control whose parent is 
the framebuffer. 

- /destroy - 

Destroy this control. This recursively destroys 
the text control and buttons. 

- /disable - 

Cause the control to stop responding to user 
actions. This recursively disables the text control 
and buttons. 
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/enable 



/enabled? 



/increment 



/location 



/minsize 



/move 



/new 



/newinit 



- /enable - 

Cause the control to respond to user actions. 

This recursively enables the text control and but- 
tons. 

- /enabled? bool 

Return true if the control is currently enabled. 

- /increment - 

Increment the value by one unit. The unit 
defaults to 1, but can be changed by the /setin- 
crement method. The increment button sends a 
/increment message. 

- /location x y 

Return the location of the origin (normally the 
lower left comer) of the control relative to the 
CTM. 

~ /minsize minwidth minheight 

Return the minimum size for this control. In 
addition to leaving room for a specified number 
of characters and text scroll buttons (see 
ClassTextControl and OpenLookTextControl), this 
method leaves room for the increment or decre- 
ment buttons. 

X y /move - 

Move the origin (lower left) of the control to the 
specified location in the coordinates of the CTM. 

notifyproc parentcanvas /new instance 
Return a new numeric control instance with the 
specified callback proc and parent canvas. The 
control initially contains no text; if asked for its 
/value it will return the /DefaultValue (q.v.). 

notifyproc /newinit 

Create the enclosed text control and buttons, 
then store the notifyproc using /newinit super 
send. 
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/notifiedvalue 



/notifyproc 



/preferreds! ze 



/reshape 



/sendtarget 



/setcolors 



/setdisplaychars 



- /notifiedvalue any 

Return the value the control had the last time 
/callnotify was sent. 

- /notifyproc proc 

Return the current callback proc without invok- 
ing it. 

- /preferredsize preferredwidth prefer- 

redheight 

Numeric controls do not presume any preferred 
size beyond the minimum required. Thus they 
use the default /preferredsize method, which 
simply calls /minsize. 

X y w h /reshape - 
Reshape the control to fit the bounding box 
specified by the arguments, in the coordinates of 
the CTM. 

args /method /sendtarget results 
This method can be invoked within the 
notifyproc in order to send a message to some 
other instance. Many clients will not need to use 
this indirection. See ClassTarget for more details. 

strokecolor fillcolor 
text color /setcolors - 
Set the colors for painting the text and its back- 
ground. Null as an argument means do not 
change that value. The strokecolor is used for 
painting the buttons. After calling /setcolors, 
clients must call /invalidate and then /paint to 
cause the text control to repaint using the new 
colors. 

n /setdisplaychars - 

Set the minimum number of characters that the 
control should be able to display. This message 
is handed off to the underlying text control, 
which uses it to deteimine /minsize. 
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/set increment 



/setmax 



/setmin 



/setnotifyproc 



/setrange 



/settarget 



increment /setincrement - 
Set the amount by which the value is changed 
by /increment and /decrement A negative 
value will cause /increment to decrease the 
value and /decrement to increase it. Setting the 
increment to zero causes the 
increment/decrement buttons to be removed 
from the control. The current increment can be 
examined via the /Increment instance variable. 

max /setmax - 

Set the maximum value permitted for the con- 
trol. Any attempt to set a value greater than the 
maximum (by typing a larger number, or by the 
/increment method) sets it instead to the max- 
imum. When the value is equal to the max- 
imum, the increment button is disabled. The ini- 
tial maximum value is 32767. 

min /setmin - 

Set the minimum value permitted for the con- 
trol. Any attempt to set a value less than the 
minimum (by typing a smaller number, or by 
the /decrement method) sets it instead to the 
minimum. When the value is equal to the max- 
imum, the decrement button is disabled. The ini- 
tial minimum value is -32767. 

proc /setnotifyproc - 

Store the proc as the new callback to be used by 
/callnotify, in place of the one provided to /new. 

min max /setrange - 

Set both the minimum and maximum values for 
the control, as described for /setmin and /set- 
max. 

object /settarget - 

Set the target used by the /sendtarget method. 
See ClassTarget for more about targets and their 
uses. 
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/settextparams 



/setvalue 



/size 



/target 



/value 



/ButtonNotify 



/ButtonY 



family polntslze encoding /settextparams 

Set the text parameters that determine the font 
for the control. This message is handed off to 
the underlying text control, as well as being 
applied to the numeric control's own canvas 
(since it affects the size of the increment or 
decrement buttons). 

n /setvalue - 

Replace the current value with the given 
number, subject to min/max constraints, and 
change the text in the text control accordingly. 

- /size w h 

Return the width and height of the control in 
the CTM. 

- /target object 

Return the current target (if any) used by 
/sendtarget See ClassTarget for more details. 

- /value num 

Return the current value of the control, obtained 
by interpreting the text control's value as a 
PostScript token. If the resulting object is neither 
/integertype nor /realtype, /value instead 
returns the /DefaultValue for the control. 

buttonlnstance /ButtonNotify - 
This is the callback used for the 
increment/decrement buttons. The default 
behavior is to send /value to the buttoninstance 
to determine which button has been pressed, 
and then send either /increment or /decrement, 
as appropriate, to the numeric control. 

- /ButtonY y 

Return the y-coordinate for positioning the 
increment/decrement buttons. By default they 
are placed so as to align with the baseline of the 
text. 
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/CallBack 



/DefaultValue 



Class Variables 

/Gap 

see also: 

ClassControl, ClassBag 



obj /CallBack - 

This is the notifyproc for the underlying text 
control. It is called when the text control 
receives a RETURN keystroke or when it loses 
the input focus, provided the text string has 
been changed. The default behavior is to nor- 
malise the value by applying the min/max con- 
straints and removing extraneous zeroes, then to 
send /checknotify which invokes the numeric 
control's own callback if the value has changed. 

/DefaultValue 

Return a default value to be used if the text 
string is unreasonable. This message is sent by 
/value and /CallBack if the string does not 
represent an integer or real value. (Thus, in par- 
ticular, an empty string will yield /DefaultValue 
rather than zero.) The default behavior is to 
return the value halfway between the minimum 
and maximum values, truncated to an integer. 
Note that the default min/max values yield a 
/DefaultValue of zero. 



This is the amount of space to leave between the 
text control and the increment/decrement but- 
tons. The default is 2. 
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OpenLookPane 

Subclass of ClassContainer 
Source file: OLpane.ps 

This class should be subclassed, rather than directly instantiated 

An OpenLookPane is a container with scrollbars and a client canvas. The 
scrollbars (none, one, or two) are not automatically connected to the canvas; this 
should be achieved via subclassing. 

see also: 

ClassContainer, OpenLookVerticalScrollbar 



OpenLookPropertyFrame 

Subclass of OpenLookFrame,ClassPropertyFrame 

Source file: OLframe.ps 

This class can be directly instantiated. 

This class is OpenLookBaseFrame with the following differences; property 
frames: 

■ have a pin 

■ do not have a footer 

■ cannot be closed into an icon (have no "iconic" state) 

■ cannot be quit from (pressing SELECT over the close box or selecting 
"Dismiss" from their menu simply unmaps them from the screen. 

see also: 

OpenLookBaseFrame 
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OpenLookTextControl 

Subclass of ClassControl 
Source file: txtctrl.ps 

This class can be directly Instantiated 

An Open Look text control augments the basic text control with Open Look 
features such as scroll buttons. (The Open Look selection features are obtained 
indirectly from ClassTextControl, which hooks into a Ul-independent mechan- 
ism). 



Direct Methods 

/callnotify 



/checknotify 



/cleartarget 



/delchar 



- /callnotify - 

Call the client's notifyproc, and also make a 
copy of the string. The copy will not be affected 
by subsequent user keystrokes, so /checknotify 
will be able to determine whether the value has 
changed. 

object I null /checknotify 
Call the client's notifyproc only if the current 
text differs from the text as of the last call to 
/callnotify. This method is called automatically 
when the text control loses the input focus, or 
when the user types the RETURN key. 

object I null /cleartarget - 
Selectively clear the target used by the /sendtar- 
get method. This method is called automatically 
when the text control is destroyed. See ClassTar- 
get for more about targets and their uses. 

n /delchar - 

Delete abs(n) characters from the text, starting at 
the current caret position. If n is negative, delete 
characters to the left of the caret, otherwise to 
the right. After the deletion, the text is scrolled 
if necessary to bring the caret into the visible 
region. 
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/delspan 



/delword 



/demo 



/destroy 



/disable 



/enable 



left rightplusone /delspan - 
Delete a span of characters from the text, 
independent of where the caret is. If the caret 
and/or a selection is within the deleted region, it 
is adjusted accordingly. Character positions start 
with zero; thus left is the number of characters 
before the first to be deleted, and the number of 
characters deleted is rightplusone minus left. 
After the deletion, the text is scrolled if neces- 
sary to bring the caret into the visible region. 

- /delword - 

Delete characters backward from the caret posi- 
tion until (a) at least one alphanumeric has been 
deleted and (b) the character ahead of the caret 
is not alphanumeric. The method 
/AlphaNumeric? is used to determine whether a 
character can be part of a word. 

- /demo instance 

Create a sample text control whose parent is the 
framebuffer. 

- /destroy - 

Destroy this control. In addition to clearing the 
target and removing the canvas from the canvas 
tree, etc., this method disables the caret, in case 
for example the caret needs to stop a forked 
process used to implement blinking. (The 
default ClassCaret does not.) The /destroy 
method also clears some cached references to the 
text control's scroll buttons, so that they can be 
destroyed as well. 

- /disable - 

Cause the control to stop responding to user 
actions. The control repaints to display its dis- 
abled status, and will no longer accept the input 
focus. 

- /enable - 

Cause the control to respond to user actions. 
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/enabled? 



/fitcaret 



/fontoffset 



/inserttext 



/invisiblecaret 



provided that it is not a read-only text control. 
The control repaints to display its enabled 
status, and will become the input focus if the 
user clicks the mouse over it. 

- /enabled? bool 

Return true if the control is currently enabled, 
even if it is read-only. 

- /fitcaret 

Call /FitCaret, which scrolls the text left or right 
to bring the caret into the visible region. 

- /fontoffset int 

Compute the vertical offset for drawing charac- 
ters without cutting them off at the bottom of 
the canvas, and also leaving enough room for 
the caret. The value is 'promoted', i.e., the first 
time /fontoffset is called it stores the resulting 
value in the instance under the name /fontoffset, 
so that subsequent calls are much faster. The 
cached value is discarded (unpromoted) if the 
canvas becomes invalid, e.g. if /settextparams is 
called. 

char I string /inserttext - 
Insert a character or a string into the text at the 
current caret position. The caret is moved to the 
end of the inserted text, and the text is scrolled 
if necessary to bring the caret into the visible 
region. If a pending-delete primary selection 
spans the caret, the selected text is deleted 
before adding the new text. Any other existing 
selections are adjusted appropriately. 

- /invisiblecaret - 

Make the caret invisible, usually in preparation 
for other operations that will cause painting. 

This method is not normally used at all, since 
the methods that cause painting (such as /insert- 
text, /delchar, etc.) all call /InvisibleCaret, which 
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/location 



/minsize 



/move 



/new 



/newinit 



/notifiedvalue 



/notifyproc 



/painttext 



assumes that the text control is the current can- 
vas. 

- /location X y 

Return the location of the origin (normally the 
lower left comer) of the text control relative to 
the CTM. 

- /minsize minwidth minheight 
Return the minimum size for this control. In 
addition to leaving room for a specified number 
of characters (see ClassTextControl), this method 
adds to the nunimum width to leave room for 
the two scroll buttons. 

X y /move - 

Move the origin (lower left) of the text control to 
the specified location in the coordinates of the 
CTM. 

notifyproc parent /new instance 
Return a new text control instance with the 
specified callback procedure and parent canvas. 
The control initially contains no text, but does 
contain a caret. 

callback /newinit 

This method does /newinit super send to store 
the callback procedure, 

then performs other initialisation specific to text 
controls. 

- /notifiedvalue string 

Return the value the control had the last time 
/callnotify was sent. 

- /notifyproc proc 

Return the current callback proc without invok- 
ing it. 

n /painttext - 

Paint the text, starting with the character at posi- 
tion nn. If character nn is off the left edge of 
the canvas, painting starts at the edge of the 
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/preferredsize 



/remove focus 



/reshape 



/restorefocus 



/scroll 



canvas. If n < 0, all the text is painted and the 
remainder of the canvas is cleared; otherwise the 
canvas is left unchanged beyond the end of the 
text. The scroll arrows, if present, are restored 
after the text is painted. This method is intended 
mainly for use from other methods; clients 
should generally send /paint to paint the con- 
trol. /painttext operates by setting the current 
canvas and font, then calling the internal 
methods /InvisibleCaret, /PaintText, and /Visi- 
bleCaret 

- /preferredsize width height 

Text controls do not presume any preferred size 
beyond the minimum required to display a cer- 
tain number of characters. Thus they use the 
default /preferredsize method, which simply 
calls /minsize. 

event /removefocus - 

Handle the input focus being moved to another 
canvas. This method disables the caret and calls 
/checknotify, which calls the client's notifyproc 
if the text has been changed. 

X y w h /reshape - 
Reshape the control to fit the bounding box 
specified by the arguments, in the coordinates of 
the CTM. 

- /restorefocus ~ 

Activate the caret if the control is enabled. This 
method is called automatically when the text 
control is given the input focus. 

n /scroll - 

Scroll the text to make a different portion visible 
within the limits of canvas. The left edge of the 
canvas always marks the beginning of a charac- 
ter; scrolling changes the character at this loca- 
tion. A positive number nn scrolls to the right; a 
negative number scrolls to the left. 
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/sendtarget 



/setcolors 



/setdisplaychars 



/setnotifyproc 



/setposition 



/setreadonly 



args /method /sendtarget results 
This method can be invoked within the 
notifyproc in order to send a message to some 
other instance. Many clients will not need to use 
this indirection. See ClassTarget for more details. 

strokecolor fillcolor 
text color /setcolors - 
Set the colors for painting the text and its back- 
ground (fillcolor). Null as an argument means 
do not change that value. The control swaps the 
fillcolor and textcolor to highlight selections. The 
strokecolor is not used used for painting the 
scroll buttons; the underlining is done using the 
textcolor so that it can be included in the 
highlighting. 

n /setdisplaychars - 

Set the minimum number of characters that the 
control should be able to display. This number 
is used in computing /minsize for the control. 
The number can be retrieved via the /Display- 
Chars variable. 

proc /setnotifyproc - 

Store the proc as the new callback to be used by 
/callnotify, in place of the one provided to /new. 

event /setposition 
n /setposition - 

Move the caret to the specified position. Position 
0 puts the caret to the left of the first character. 

If an event is given, the coordinates in the event 
are resolved to the nearest character boundary. 
The current caret location can be obtained from 
the variable /Left Once the caret is placed, the 
text is scrolled if necessary to bring the caret 
into the visible region. 

bool /setreadonly 

Make the text read-only or not, depending on 
the bool. If the text becomes read-only, the 
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/settarget 



/settextparams 



/setvalue 



/size 



/starttext 



/ St opt ext 



/strlen 



canvas is removed from the list of potential 
input foci; if it becomes writeable it is added 
back. A read-only text control behaves much the 
same as a disabled one (see /disable), the main 
difference being that a disabled control will typi- 
cally be painted light gray, whereas a read-only 
one will paint normally. 

object /settaiget - 

Set the target used by the /sendtarget method. 
See ClassTarget for more about targets and their 
uses. 

family pointsize encoding /settextparams 
Set the text parameters that determine the font 
for the control. If any of the arguments is null, 
that parameter is not changed. The control then 
marks itself as invalid (i.e., calls /invalidate) so 
that various cached values such as /fontoffset 
and the font itself will be recomputed. 

string /setvalue 

Replace the contents of the text control with the 
given string. If the string differs from the old 
contents, the control is repainted. 

- /size w h 

Return the width and height of the control in 
the CTM. 

- /starttext - 

This method enables the caret. It is called from 
/restorefocus. 

- /stoptext - 

This method disables the caret. It is called from 
/removefocus and /destroy. Clients may also 
need to send /stoptext to newly created text con- 
trols to disable their initial carets. 

- /strlen n 

Return the number of characters of text 
currently stored in the control. This method is 
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/target 

1 

/ vaxuc 

/visiblecaret 



Subclass Methods 

/AlphaNumeric? 



/CaretPosition 

/DeHighlight 



equivalent to, but more efficient than, /value 
length. 

“ /target object 

Return the current target (if any) used by 
/sendtarget See ClassTarget for more details. 

- /value string 

Return the contents of the control as a PostScript 
string. If the string is empty, a zero-length string 
is returned, not null. 

- /visiblecaret - 

Make the caret visible, usually after other paint- 
ing has finished. This method is not normally 
used at all, since the methods that cause paint- 
ing (such as /inserttext /delchar, etc.) all call 
/VisibleCaret, which assumes that the text con- 
trol is the current canvas. 



n /AlphaNumeric? bool 

Determine whether the character at the specified 

index is part of a word. This method is called by 

/delword, and also when making word-level 

selections. The default method texts for letters, 

digits, and underscore. See /AlphaNumericT- 

able, 

- /CaretPosition x 

Return the x-coordinate of the caret relative to 
the left edge of the canvas. 

start end /DeHighlight last 
Paint the characters in positions startsfart 
through endend-1, and return the index of the 
next character to be painted. The characters are 
painted using the canvas's /FillColor as back- 
ground and /TextColor for the text and under- 
line. This method is called by /PaintText and in 
turn calls /PaintNText 
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/EOL 



/FitCaret 



/Highlight 



/ Interest ingRank 



/PaintText 



- /EOL - 

This method is called when either a RETURN 
CM) or NEWLINE CJ) character is typed into 
the control. It calls /checknotify. 

/method /FitCaret bool 
Scroll the text so as to bring the current caret 
position into the region between the left and 
right edges of the canvas. Return true if any 
scrolling was done, so the caller will know to 
repaint the text. (/FitCaret does not itself do any 
painting.) The method-name parameter is 
ignored; OpenLookTextControls scroll after all 
relevant operations. 

start end /Highlight last 
This is the same as /DeHighlight except the 
background and foreground colors are reversed. 
It is called by /PaintText for painting characters 
within the primary selection. 

rank /InterestingRank bool 
Return true if the selection rank is one that the 
text control knows how to deal with. By default 
the only interesting ranks are /PrimarySelection 
and /SecondarySelection. (/ShelfSelection is 
handled by the global UI mechanism.) For each 
interesting rank there is also a correspondingly 
named instance variable, used for maintaining 
information about that selection. (These vari- 
ables are of no interest to clients or subclassers, 
except insofar as subclassers must be careful not 
to use those variable names for other informa- 
tion.) 

n /PaintText - 

This method performs most of the work of 
/painttext. It can assume that the text control's 
canvas is the current canvas> and the control's 
font is the current font. OpenLookTextControl 
overrides /PaintText to include repainting the 
scroll buttons after the text is drawn. 
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/PaintNText 



/TextBegin 



/TextEnd 

Class Variables 

/AlphaNumericTable 



/DisplayChars 



textcolor backcolor start 
end /PaintNText last 
This method is called by /Highlight and 
/DeHighlight to paint portions of the text using 
the given colors for the text and background. 
The characters painted are those in positions 
start through end-i. This range may be empty. 
/PaintNText returns the index of the next char- 
acter to be painted, the larger of end and start. 
This method assumes that the text control is the 
current canvas and the control's font is the 
current font. OpenLookTextControl overrides 
/PaintNText to underline the text (using the 
supplied textcolor). 

- /TextBegin - 

Save the graphics context, then set the text 
control's canvas and font as the current canvas 
and font. This method is called at the beginning 
of several other methods to establish the context 
for painting and other CTM-based operations. 

- /TextEnd 

Restore the graphics context saved by /TextBe- 
gin. 



This is a dictionary whose keys are single char- 
acters (integers). The associated values are 
ignored. A character appears as a key if and 
only if that character is considered part of a 
word. This dictionary is used by 
/AlphaNumeric?, and can be overridden by sub- 
classers to change the definition of word- 
selection and /delword. See ClassTextControl for 
a warning regarding subclassing this variable. 

The minimum number of characters that the 
control should be able to display. The default 
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/Left 

/Readonly? 



see also: 

ClassTextControl 



value is 5, unless overridden by subclassing or 
by /setdisplaychars. 

The number of characters to the left of the caret; 
hence, the current caret position. 

True if the control is read-oitly. This value 
defaults to false, but can be overridden by sub- 
classers or /setreadonly. 



OpenLookVerticaiScrollbar 

Subclass of OpenLookHorizontalScrollbar 
Source file: OLSbar.ps 

This class can be directly Instantiated 

An OpenLookVerticaiScrollbar is an analog control that allows the user to scroll 
through a large document, for example. It is the default vertical scrollbar for an 
OPEN LOOK pane. This entry also covers OpenLookHorizontalScrollbar. The 
only differences between the two are: 

■ OpenLookVerticaiScrollbar has an origin in the upper left comer, whereas 
OpenLookHorizontalScrollbar uses the standard lower left origin. 

■ The menu associated with OpenLookVerticaiScrollbar has "Here to top", 
whereas OpenLookHorizontalScrollbar has "Here to left" 



Direct Methods 

/abbreviated? — /abbreviated? bool 

Returns true if the scrollbar is displayed in its 
abbreviated form: with the two arrow controls, 
but no drag box. 

/destroy — /destroy — 

This destroys the scrollbar menu, and then des- 
troys the scrollbar itself. 
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/disable 

/enable 

/exchlastvalue 

/heretostart 



/menu 

/minsize 

/new 

/newinit 



— /disable — 

This disables the scrollbar. The scrollbar will be 
repainted to show that it is disabled, and the 
mouse clicks will have no affect. 

— /enable — 

This is the opposite of disable. The scrollbar is 
repainted to indicate that it is enabled, and 
mouse clicks will be accepted again. 

— /exchlastvalue — 

This exchanges the current scrollbar value with 
the previous value. 

event /heretostart — 

X y /heretostart — 

Increments the scrollbar value by part of a view, 
/heretostart expects an x/y pair or an event 
(which it then turns into an x/y pair). The new 
value of the scrollbar will be such that the part 
of the document at the x/y position will be 
displayed at the top of the view. This is how 
HereToTop is implemented. 

— /menu menu 
Returns the scrollbar menu. 

— /minsize min width minheight 
Returns the size of the scrollbar in its abbrevi- 
ated form. 

notifyproc parent /new scrollbar 
Creates a scrollbar with the specified notify 
proc. The parent canvas is consumed by 
/newobject, /notifyproc is consumed by 
/newinit. 

notifyproc /newinit 

This method is called by /new to initialize the 
instance. The notifyproc is consumed by 
ClassControl's /newinit. This also creates the 
scrollbar's anchor and elevator controls. 
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/preferreds! ze 



/setdelta 



/setnienu 



/set range 



/starttohere 



— /preferredsize preferredwidth prefer- 
redheight 

Often preferredsize is the same as minsize, but 
in the case of OpenLook scrollbars, /preferred- 
size is the size to fit the entire elevator, /min- 
size is the size of an abbreviated scrollbar, and 
/preferredsize is the next size up from that. 

name value /setdelta — 

The scrollbar deltas are named /Line, /Page and 
/Document, and they specify how much to 
increase or decrease the value of the scrollbar 
when the user selects a particular type of scrol- 
ling. Typical values for these deltas might be 
specified in units of lines, and so /Line would 
be set to 1, /Page would be the number of lines 
visible in a page, and /Document would be the 
number of lines in the document. 

menu /setmenu — 

Set the menu for the scrollbar. You do not nor- 
mally need to call this method as OpenLook 
scrollbars come with a standard menu. 

min max /setrange — 

Set the range of the scrollbar. 

event /starttohere — 

X y /starttohere — 

Decrements the scrollbar value by part of a 
view. / starttohere expects an x/y pair or an 
event (which it then turns into an x/y pair). 

The new value of the scrollbar will be such that 
the part of the document at the top of the view 
will now be displayed at the specified x/y posi- 
tion. This is how TopToHere is implemented. 
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Subclass Methods 

event /ClientDown — 

This method is called when the user mouses 
down over the scrollbar. This saves away the 
current value of the scrollbar, and then 
processes the mouse event. 

event /ClientUp — 

This method is called when the user lets go of 
the mouse button that caused /ClientDown to 
be called. 

anchor-control /MaxHit 
Called when the high anchor button is hit. 

anchor-control /MinHit — 

Called when the low anchor button is hit. 

value /PaintCable 

Called to paint the scrollbar's cable and propor- 
tion indicator. 

/PaintCanvas — /PaintCanvas — 

Called to paint the entire scrollbar. 

/PaintValue value /PaintValue 

Paints the scrollbar with specified value. 



/ClientDown 

/ClientUp 

/MaxHit 

/MinHit 

/PaintCable 



OpenLookVerticalSlider 

Subclass of OpenLookHorizontalSlider 
Source file: OLslider.ps 

This class can be directly Instantiated 

This slider is a horizontal OPEN LOOK slideattr rotated 90”; it has the same 
interface as OpenLookVerticalSlider. 
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see also: 

OpenLookHorizontalSlider 



OpenLookXSetting 

Subclass of RowColumnLayout,ClassSelectionList 

Source file: OLxset.ps 

This class can be directly instantiated. 

This class implements an Open Look exclusive setting group. The group 
displays multiple setting items on a single canvas. The group acts like a control 
in that it has a single value. Each item has an associated notify procedure that 
is called when the item is selected. 



Direct Methods 

/border 



/change 



/cleartarget 



/client count 



/clientlist 



- /border maiiber 

Return the size of the border around the entire 
group of settings. 

location thing I graphic 

genproc | sublist | null proc | null /change 

Change the setting item at the specified location. 
The parameters, other than location, are the 
same as for /new. 

object I null /cleartarget 
Clear the control's target object. If an object is 
supplied as a parameter, the target will be 
cleared only if the current target matches the 
parameter. See ClassTarget for more about tar- 
gets and their uses. 

- /clientcount n 

Return the number of items in the setting. 

- /clientlist array 

Return an array of dictionaries, one per item in 
the control group. 
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/delete 

/demo 

/destroy 

/disableitem 

/doaction 

/enableitem 

/gaps 

/graphic 

/insert 



/invalidate 

/itemcount 

/itemenabled? 



location /delete - 

Delete the specified setting item from the group. 

- /demo instance 

Create a demonstration exclusive setting on the 
framebuffer. 

- /destroy - 

Destroy the exclusive setting control. 

index /disableitem - 

Disable the item at the specified location. 

~ /doaction - 

Execute the notify proc associated with the 
currently selected setting item. i.e. the item 
whose index matches the setting's current value. 

index /enableitem ~ 

Enable the item at the specified location. 

~ /gaps horizontalgap verticalgap 
Return the amount of space between the setting 
items. By default, and by the OPEN LOOK 
specification, the values are both 0. 

location /graphic graphic 

Return the graphic for the specified setting item. 

location thing | graphic 

genproc I sublist I null proc I null /insert - 
Insert a new setting item at the specified posi- 
tion in the group. The parameters, other than 
location, are the same as for /new. 

- /invalidate -- 

Invalidate the setting and all of its item graph- 
ics. 



“ /itemcount integer 

Return the number of items in the setting group. 

location /itemenabled? bool 
Return true if the specified item is enabled. 
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/layout 

/layout style 

/location 

/maxlocation 

/minsize 

/move 

/new 



/notifyproc 

/preferredsize 

/reshape 

/ searchgraphic 



- /layout - 

Lay out the setting items. This sizes and places 
the items according to the layout style for the 
setting. 

- /layoutstyle RowMajor? Rows | null 
Columns I null 

Return the layout style for the menu. See class 
RowColumnLayout. 

- /location x y 

Return the location of the setting canvas. 

- /maxlocation location 

The location of the last item in the control. Item 
locations range from 0 to /maxlocation. /maxlo- 
cation is one less than /itemcounL 

- /minsize minwidth minheight 
Return the minimum size of the setting. 

X y /move - 

Move the setting's canvas to the specified loca- 
tion, relative to the CTM. 

[thing I graphic proc | null . . . ] 

Ccinvas /new instance 
Create an exclusive setting group. Refer to the 
introductory section OPEN LOOK Settings for 
the details of the arguments. 

location /notifyproc procedure | null 
Return the notify proc for the item at the 
specified location. 

- /preferredsize width height 

Return the preferred size of the setting group. 

X y w h /reshape 

Reshape the setting group's canvas. Invalidates 
the setting group. 

graphic /searchgraphic index true 

graphic /searchgraphic false 
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/searchthing 



/sendtarget 



/setborder 



/setgaps 



/setgraphic 



/set layout style 



/set layout style 



graphic start loc /searchgraphic index 

true 

graphic startloc /searchgraphic false 

Search for the setting item having the given 
graphic. If a starting location is given, begin the 
search at that item. The search ends with the 
last menu item and does not wrap around. 

thing /searchthing index true 

thing /searchthing false 

thing startloc /searchthing index true 

thing startloc /searchthing false 

Search for the setting item having the given 
thing in its graphic. If a starting location is 
given, begin the search at that item. The search 
ends with the last menu item and does not wrap 
around. 

args /method /sendtarget results 
Send a message to the target object. Typically 
used in the control's notify proc. See ClassTarget 
for more details. 

number /setborder - 

Set the size of the border around the entire 

group of settings. 

horizontalgap I null 

verticalgap Inull /setgaps - 

Change the amount of space between the setting 

items. A null parameter leaves that value 

unchanged. 

location thing | graphic /setgraphic - 
Change the graphic for the specified setting 
item. 

RowMajor? Rows [null 
Columns I nul 1 /setlayoutstyle 

RowMajor? Rows Inull 
Columns Inull /setlayoutstyle 
Change the layout style of the menu. 
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/setnotifyproc 



/settarget 

/setvalue 

/size 

/target 

/value 

/valuething 



See RowColumnLayout, 

location procedure 1 null /setnotifyproc 
Change the notification procedure (callback) 
associated with a setting item. Note that if you 
specify a single notify proc when creating the 
setting group, the notify proc is duplicated for 
each item. You may therefore change individual 
item callbacks without affecting others. Also, to 
change the callbacks for all items, you must call 
/setnotifyproc for each item. 

object /settarget 

Set the target used by the /sendtarget method. 
See CkssTarget for more about targets and their 
uses. 

index /setvalue - 

Change the value of the setting. The item 
corresponding to the supplied index is selected 
and the previously selected item, if there was 
one, is deselected. 

- /size w h 

Validate the setting and return its size in the 
coordinates of the CTM. 

- /target object 

Return the target object. See ClassTarget, 

- /value index 

Return the location of the selected item. The 
first item is number 0. Returns null if there is 
no selected item. Note that this can happen if 
the value is never changed from its initial value 
or if it is explicitly set to null with /setvalue. It 
can not happen as the result of a user interac- 
tion. 

- /valuething thing I null 

Return the thing of the graphic of the selected 
item. Returns null if the /value of the setting is 
null. 
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Subclass Methods 

/DeHighlight index /DeHighlight 

/Highlight index /Highlight - 

see also: 

RowColumnLayout,ClassSelectionList 

OpenLookXSettingControl 

Subclass of Open Look Button 
Source file: OLxctrl.ps 

This class should be subclassed, rather than instantiated directiy. 

This class exists only as a superclass to OpenLookCheckBox. Its purpose is to 
make a control out of a single setting item. . 

see also: 

OpenLookButton, OpenLookCheckBox 



RowColumnBag 

Subclass of RowColumnLayout,ClassBag 
Source file: bagutils.ps 

This class may be directly instantiated. 

A RowColumnBag is a general purpose bag in which the clients are layed out 
on an equally spaced matrix. The interface for controlling this matrix is the same 
as that offered in class RowColurrmLayout, one of the ancestors of this class. 

The interface is also similar to that used in OpenLookMenu for laying out menu 
items. 
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Direct Methods 

/addclient 



/border 

/clientcount 



/clientlist 



/destroy 



/gaps 



/layoutstyle 



name I null client /addclient 

name I null [client_class args 

client_class] /addclient - 

Add a client to the bag. The client may be 

specified by either an instance or by a class to 

instantiate, with the arguments necessary to do 

so. 

No baggage needs to be specified, since the 
clients will be layed out as a matrix specified by 
/setlayoutstyle. The clients are stored in a linear 
array in the order they are inserted into the bag. 
This array is then mapped onto the matrix that 
is displayed. 

- /border int 

- /clientcount n 

Return the number of clients currently in the 
bag. 

- /clientlist [clientl client2 ...] 

Return an array of clients in the same order as 
they were inserted into the bag. 

- /destroy - 

Destroy the bag and its clients. Refer to the Ides- 
troy method in ClassBag for the additional infor- 
mation on the use of this method. 

- /gaps horizontalgap verticalgap 
Return the horizontal and vertical gaps between 
cells in the matrix to be layed out, as specified 
by /setgaps. 

- /layoutstyle RowMajor? Rows | null 
Columns I null 

Return the layout specification as described in 
class RowColumnLayout. The three arguments 
returned indicate whether row or column order 
is used, how many rows, and how many 
columns. 
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/location 



/minsize 



/move 



/new 



/preferredsize 



/removeclient 



/reshape 



/sendclient 



~ /location x y 

Return the location of the origin of the bag in 
the coordinates of the CTM. 

/minsize xninwidth minheight 
Compute the minimum acceptable size for this 
bag- as if all clients were as big as the largest 
minimum size of any client. A well behaved 
application will respect this size when reshaping 
the bag in response to user mouse actions. 

X y /move - 

Move the origin of the canvas to the specified 
location in the coordinates of the CTM. 

parentcanvas /new instance 
Create an instance of class RowColumnBag. 

- /prefeiredsize preferredwidth prefer- 
redheight 

Calculate the "ideal" size of the bag, which 
defaults to the minimum size. Well behaved 
applications should respect this size when ini- 
tially displayed the bag. 

client I name In /removeclient oldclient 
true 

client I name | n /removeclient false 
Remove the client given, named or indexed in 
the argument. The method returns true and the 
client object if the client is found, otherwise it 
returns false. Refer to the /removeclient 
method in ClassBag for the additional informa- 
tion on the use of this method. 

X y w h /reshape 

Reshape the bag to the dimensions given and 
invalidate it. This will later result in the bag 
being layed out as the first step in painting it. 

<args> /method /name /sendclient results 
Send the given method with arguments to the 
named client 
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/setborder n;jinber /setborder - 

Set the space used at the border of the matrix, 
and invalidate to mark the matrix as needing 
layout. 

/setgaps horizontalgap I null 

verticalgap I null /setgaps 
Set the horizontal and vertical spacing between 
cells in the matrix, and invalidate to mark the 
matrix as needing layout. If either argument is 
null, that spacing is not changed. 

/ set layout style RowMa jor? Rows | null 

Columns I null /setlayoutstyle 

Set the layout parameters of the matrix, and 

invalidate to mark it as needing layout. 

/size - /size w h 

Return the width and height of the canvas in 
CTM. 

see also: 

RowColumnLayout,ClassBag 

RowColumnLayout 

Subclass of Object 
Source file: OLutil.ps 

This class should be mixed into another subclass rather than directly 
instantiated. 

This class is a mix-in to perform grid-style layout and point location on a can- 
vas. It has a similar interface and behavior to the layout code found in 
ClassMenu. 

The basic idea behind laying out rows and columns is to specify the size of a 2 
dimensional matrix and how to fill it in from a 1 dimensional array of elements. 
The argument listed below as RowMa jor? is a boolean specifying how to fill in 
the matrix: 

true = Row major order, fill rows first 
false = Column major order, fill columns first 
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The size of the matrix is specified by arguments listed below as Rows | null and 
Columns | null. 

■ both arguments are specified numerically, 

the layout has that number of rows and columns, and if there are more 
items than will fit into the specified matrix, those items are not displayed. 

a both are null, 

use the default layout specification, as given by /setlayoutstyle. 

a one is specified numerically and one is null, 

then the matrix has the specified number of rows or columns and what- 
ever number of columns or rows are needed to display all the items. 



Thus, a 7 item array with 3 rows and null columns is displayed as follows, 
depending on whether row major or column major order was specified: 



Row Major 
0 1 2 

3 4 5 

6 



Column Major 

0 3 6 

1 4 

2 5 



Direct Methods 




/border 


- /border number 

Return the size of the borders around the 
matrix. 


/cellcount 


- /cellcount columns rows 

Return the number of colunrms and rows to be 

used in laying out the matrix. 


/gaps 


- /gaps horizontalgap verticalgap 
Return the horizontal and vertical gaps between 
cells in the matrix to be layed out. 


/invalidate 


- /invalidate - 

Remove previously stored values for heights 
and widths and invalidate the nnatrix to mark it 
as needing layout. The values discarded are: 
/ArrayHeight, /ArrayWidth, /MinCellHeight, 
/MinCellWidth, /CellHeight, /CellWidth, 
/CellCols, /CellRows. 
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/layoutstyle 



/setborder 

/setgaps 



/set layout style 



Subclass Methods 

/ArrayHeight 

/ArrayWidth 

/CellCols 



/CellHeight 



- /layoutstyle RowMajor? Rows | null 
Columns I null 

Return the layout specification, as described 
above: row or column order, how many rows 
and how many colunrins. 

nximber /setborder - 

Set the space used at the border of the matrix, 
and invalidate to mark the matrix as needing 
layout. 

horizontalgap I null 

verticalgap I null /setgaps 

Set the horizontal and vertical spacing between 

cells in the matrix, and invalidate to mark the 

matrix as needing layout. If either argument is 

null, that spacing is not changed. 

RowMajor? Rows | null 

Columns I null /setlayoutstyle 

Set the layout parameters of the matrix, and 

invalidate to mark it as needing layout. 



- /ArrayHeight arrayheight 

Return the height of the entire matrix, with gaps 
and borders. 

“ /ArrayWidth arraywidth 

Return the width of the entire matrix, with gaps 

and borders. 

- /CellCols cols 

Return the number of columns to be used in lay- 
ing out the matrix. This number was either sup- 
plied as an argument or it is calculated from the 
specified layout and the number of rows. 

- /CellHeight cellheight 

Return the height of a cell in the matrix. This is 
the maximum height of any item plus the verti- 
cal cell spacing (CellVertGap). 
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/CellRows 



/CellWidth 



/Layout 



/MinSize 



/XYToValue 



- /CellRows rows 

Return the number of rows to be used in laying 
out the matrix. This number was either sup- 
plied as an argument or it is calculated from the 
specified layout and the number of columns. 

- /CellWidth cell width 

Return the width of a cell in the matrix. This is 
the maximum width of any item plus the hor- 
izontal cell spacing (CellHorzGap). 

“ /Layout - 

This method calls /Rowcolumnlayout to per- 
form the actual layout of the matrix. 

- /MinSize minw minh 

Returns the minimum width and height for the 
matrix. This is detemrdned by the largest 
minimum size of all objects being layed out. 

X y /XYToValue index [null 
This method converts a location on the canvas 
into the index of the matrix item that contains 
the location. The method returns null if the 
location is not in the canvas area occupied by 
the matrix. 



Class Variables 

/Border 

/CellHorzGap 

/CellVertGap 

/Layout Cols 

/LayoutRows 



This variable stores the size of the border. 

This variable stores the horizontal gap (distance) 
between cells in the layout. 

This variable stores the vertical distance between 
cells in the layout. 

This variable stores the number of columns to be 
used in laying out the matrix; by default the 
value is 1 

This variable stores the number of rows to be 
used in laying out the matrix. By default the 
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/RowMajor? 

see also: 

Object 



value is null, which means to use as many rows 
as necessary. 

This variable stores the boolean specifying row 
major order (true) or column major order (false). 
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